{"type":"doc","content":[{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph","content":[{"text":"Table of Contents","type":"text","marks":[{"type":"strong"}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"2"},"maxLevel":{"value":"2"},"outline":{"value":"false"},"style":{"value":"disc"},"type":{"value":"list"},"printable":{"value":"true"}},"macroMetadata":{"macroId":{"value":"61238332-bf9b-4488-b70b-6e3bac86513a"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"c4d3f7d6-82a9-4778-af33-6fd7dc6cffa8"}}]},{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"About Single Sign-On","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Beginning with the 8.0 release, CollectionSpace supports integration with single sign-on providers using SAML. Single sign-on can be enabled by adding connection information to a services configuration XML file.","type":"text"}]}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"NOTE: This documentation is for Self-Hosted installations of CollectionSpace. Lyraris-hosting will configure SSO for hosted clients.","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Creating a file to store local configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"Your configuration file should be placed in the ","type":"text"},{"text":"$CSPACE_JEESERVER_HOME/cspace/config/services/local","type":"text","marks":[{"type":"code"}]},{"text":" directory on the CollectionSpace server.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Create the ","type":"text"},{"text":"local","type":"text","marks":[{"type":"code"}]},{"text":" directory if it does not exist.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Inside that directory, create a file with any name of your choosing, ending with","type":"text"},{"text":".xml","type":"text","marks":[{"type":"code"}]},{"text":"; for example, ","type":"text"},{"text":"services-config-sso.xml","type":"text","marks":[{"type":"code"}]},{"text":". This local configuration file will be merged with the","type":"text"},{"text":"services-config.xml","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"services-config-security.xml","type":"text","marks":[{"type":"code"}]},{"text":" files, found in ","type":"text"},{"text":"$CSPACE_JEESERVER_HOME/cspace/config/services","type":"text","marks":[{"type":"code"}]},{"text":". You may add more than one ","type":"text"},{"text":".xml","type":"text","marks":[{"type":"code"}]},{"text":" file to the ","type":"text"},{"text":"local","type":"text","marks":[{"type":"code"}]},{"text":" directory if you want to split your configuration into multiple files. If more than one ","type":"text"},{"text":".xml","type":"text","marks":[{"type":"code"}]},{"text":" file is present in ","type":"text"},{"text":"local","type":"text","marks":[{"type":"code"}]},{"text":", the files are merged into the configuration in alphabetical order.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add configuration to your file(s), following the example and instructions below.","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Your local configuration is merged with the default configuration files when CollectionSpace starts. For debugging, the output of the merge is written to ","type":"text"},{"text":"$CSPACE_JEESERVER_HOME/cspace/config/services/service-config.merged.xml","type":"text","marks":[{"type":"code"}]}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"SAML configuration settings","type":"text"}]},{"type":"paragraph","content":[{"text":"Your merged XML file must conform to the XML schema at ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/collectionspace/services/blob/v8.0-branch/services/config/src/main/resources/service-config.xsd"}},{"text":" . That schema defines the ","type":"text"},{"text":"security/sso/saml","type":"text","marks":[{"type":"code"}]},{"text":" element that contains the configuration for SAML SSO.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following example shows a typical SSO configuration file:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\n \n \n \n \n \n \n Auth0\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The merge result can be fine tuned by adding attributes from the ","type":"text"},{"text":"merge","type":"text","marks":[{"type":"code"}]},{"text":" namespace defined in the example. In most cases, the default merge behavior (no merge attributes, as above) is sufficient. See the ","type":"text"},{"text":"XmlMerge documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/collectionspace/services/blob/master/services/common/src/main/cspace/config/services/tenants/XMLMerge-README.pdf"}}]},{"text":" for details.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Some important elements inside ","type":"text"},{"text":"saml","type":"text","marks":[{"type":"code"}]},{"text":" include:","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"single-logout","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"The presence of this element enables SAML single logout (SLO). At present, only RP-initiated logout (logging out of CollectionSpace also logs the user out of the SAML identity provider) is supported. AP-initiated logout (logging out of the SAML IdP also logs the user out of CollectionSpace) may be supported in the future.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Enabling single logout enables the feature for ","type":"text"},{"text":"every","type":"text","marks":[{"type":"em"}]},{"text":" registered relying party. There is currently no way to enable SLO only for certain relying parties.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"If single logout is enabled, credentials for signing must be present in the configuration of ","type":"text"},{"text":"every","type":"text","marks":[{"type":"em"}]},{"text":" registered relying party, since single logout requests must be signed.","type":"text"}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"relying-party-registrations","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Registers SAML relying parties. A ","type":"text"},{"text":"relying-party","type":"text","marks":[{"type":"code"}]},{"text":" in this configuration file can be thought of as a connection between CollectionSpace and a SAML identity provider.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"relying-party","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"Configures a connection between CollectionSpace and a SAML IdP.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"The required","type":"text"},{"text":" id","type":"text","marks":[{"type":"code"}]},{"text":" attribute specifies a registration ID that must be unique among all relying parties.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":1}}],"content":[{"text":"This ID appears in the URLs of CSpace REST API endpoints. For readability, it is recommended to use only URL-friendly characters.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"name","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"The user-friendly name of the connection. This is used in the user interface, so it should be human readable, and familiar to end-users of the identity provider. The metadata provided by an IdP sometimes contains a suitable name, but this setting currently is not automatically configured from the metadata.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"If the ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" element is not present, the ","type":"text"},{"text":"id","type":"text","marks":[{"type":"code"}]},{"text":" is displayed in the user interface.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"icon","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"An icon (logo) image to use in the user interface for this connection. The metadata provided by an IdP sometimes contains a suitable image, but this setting currently is not automatically configured from the metadata.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"The required ","type":"text"},{"text":"location","type":"text","marks":[{"type":"code"}]},{"text":" attribute contains the URL of the image. This may be a ","type":"text"},{"text":"file://","type":"text","marks":[{"type":"code"}]},{"text":" URL, if the image can be found in a local file.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"If ","type":"text"},{"text":"the icon","type":"text","marks":[{"type":"code"}]},{"text":" element is not present, a default icon is displayed in the user interface.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"metadata","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"The XML-formatted metadata provided by the SAML identity provider.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"The required ","type":"text"},{"text":"location","type":"text","marks":[{"type":"code"}]},{"text":" attribute contains the URL of the metadata. This may be a ","type":"text"},{"text":"file://","type":"text","marks":[{"type":"code"}]},{"text":" URL, if the metadata can be found in a local file.","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"assertion-username-probes","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"A list of locations in a SAML assertion returned by the identity provider to look for the username of a CollectionSpace user. A location is either an attribute in the assertion or the NameID of the assertion. Each location is probed in the order given. If it contains something that looks like an email address, an attempt is made to locate a CSpace user whose username is equal to that email. Once a user is found, probing of locations stops.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"name-id","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"Specifies that the NameID of the assertion is a possible location of the email/username.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"attribute","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"Specifies that an attribute in the assertion is a possible location of the email/username. The required ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code"}]},{"text":" attribute specifies the name of the attribute in the assertion.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"Defaults to:","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"signing-x509-credentials","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"A list of credentials to use for signing SAML requests issued by CollectionSpace. Typically, you will only specify a single credential (private key and certificate pair). A credential is required if the identity provider requires login requests to be signed (as reported in its metadata), or if single logout is enabled. Otherwise, signing credentials are optional.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"x509-credential","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":3}}],"content":[{"text":"A signing credential.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":"private-key","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":"The private key to be used for signing. The key can either be specified in the content of the element, or as a URL.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"If the private key is entered as content, be sure to treat this configuration file as a secret.","type":"text"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":"If the key is not set as the content of the element, use the ","type":"text"},{"text":"location","type":"text","marks":[{"type":"code"}]},{"text":" attribute to specify the URL where the key can be found. This may be a ","type":"text"},{"text":"file://","type":"text","marks":[{"type":"code"}]},{"text":" URL, if the key can be found in a local file.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":"For an example, see: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/spring-projects/spring-security-samples/blob/5.8.x/servlet/xml/java/saml2/login-logout/src/main/resources/credentials/rp-private.key"}},{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":"x509-certificate","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":"The certificate to be used to validate a document signed with the private key. The certificate can either be specified in the content of the element, or as a URL.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":"If the certificate is not set as the content of the element, use the ","type":"text"},{"text":"location","type":"text","marks":[{"type":"code"}]},{"text":" attribute to specify the URL where the certificate can be found. This may be a ","type":"text"},{"text":"file://","type":"text","marks":[{"type":"code"}]},{"text":" URL, if the certificate can be found in a local file.","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":4}}],"content":[{"text":"For an example, see: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/spring-projects/spring-security-samples/blob/5.8.x/servlet/xml/java/saml2/login-logout/src/main/resources/credentials/rp-certificate.crt"}},{"text":" ","type":"text"}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"decryption-x509-credentials","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}],"content":[{"text":"A list of credentials to use for encrypting and decrypting SAML assertions issued by the IdP. Typically, you will only specify a single credential (private key and certificate pair). A credential is required if the identity provider requires its assertions to be encrypted. Otherwise, decryption credentials are optional. The content of ","type":"text"},{"text":"decryption-x509-credentials","type":"text","marks":[{"type":"code"}]},{"text":" has the same structure as ","type":"text"},{"text":"signing-x509-credentials","type":"text","marks":[{"type":"code"}]},{"text":", but the decryption and signing credentials may differ.","type":"text"}]},{"type":"paragraph"},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Retrieving CollectionSpace SAML Metadata","type":"text"}]},{"type":"paragraph","content":[{"text":"Restart the CollectionSpace server to activate your SSO configuration. CollectionSpace SAML metadata for a configured relying party can be retrieved from the REST API at:","type":"text"}]},{"type":"paragraph","content":[{"text":"/cspace-services/saml2/service-provider-metadata/{id}","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"(Replace ","type":"text"},{"text":"{id}","type":"text","marks":[{"type":"code"}]},{"text":" with the value of the ","type":"text"},{"text":"id","type":"text","marks":[{"type":"code"}]},{"text":" attribute of the ","type":"text"},{"text":"relying-party","type":"text","marks":[{"type":"code"}]},{"text":" in your configuration).","type":"text"}]},{"type":"paragraph","content":[{"text":"This URL can be provided to the administrator of the SAML identity provider in order to complete the connection.","type":"text"}]},{"type":"rule"}],"version":1}

Browser not supported