Saml2

Administration Page Application/Contract Syracuse/Collaboration class saml2s Representation saml2

When a user signs for Sage X3, the user's account must be authenticated in order to be granted access to the application functions. User authentication is usually handled within the application using a database or an LDAP server. However, for SAML2 (as well as for OAuth2), the application grants access only when authentication by a dedicated external server is successful.

Principles of SAML2 authentication SAML2 instance definition SAML2 configuration Limitations

Principles of SAML2 authentication

SAML2 identity provider is an independent server that is intended for user authentication according to the SAML2 method. When a user's login clears this server, the application is notified so that the user can get access.

Before using this authentication mode, you need to register your application with the SAML2 identity provider to obtain access. You only register once and it requires you to provide the following information and elements:

  • A redirect URI (consisting of the protocol, hostname, port together with the callback path from below).
  • The issuer (see below).
  • An optional certificate when it is necessary to verify a signed authorization request.
  • Some SAML2 identity providers require a metadata file; this can be obtained by the service Get metadata below.

Assuming that the application has been registered, the following process activates when the user logs in:

  1. The application redirects the user to the SAML2 identity provider and provides data from within the authorization request.
  2. The SAML2 identity provider asks the user to log in unless the user is already logged in with the SAML2 identity provider.
  3. After a successful log in, the SAML2 identity provider returns information about the user, which is mapped to an application user.

An instance of the user entity should be available for this user who must be marked for SAML2 authentication with this particular server. Then the user can access the application. Login can also be initiated by the SAML2 identity provider.

There is also an optional mechanism for single logout: Here the SAML2 identity provider sends a logout request to the application and the application will finish all sessions which have been started via this SAML2 identity provider as soon as possible.

SAML2 instance definition

The following global configuration is necessary for this authentication:

Name

The name is used to reference the SAML2 setup. It must not be changed after creating the instance because the redirect URL depends on the name.

Display name

A user-friendly description.

Active

If the check box is cleared, the server is considered "inactive" and no additional log in is possible using this setup.

Authorize URL

Defines the full URL (including protocol, server name, port, path) of the SAML2 identity provider, which is used as the destination for the authorization request. For example: `https://saml2.test.de/SAML2/example.pl`. This URL can also be seen in the metadata file of the SAML2 identity provider. It is contained in the `Location` attribute of the `SingleSignOnService` tag for HTTP-Redirect (or HTTP-POST) binding, e. g.,
CODECODE CODExml
<ns0:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://testserver:8000/idp/saml2/sso"/>

Logout response URL

Defines the full URL (including protocol, server name, port, path) of the SAML2 identity provider, which is used as the destination for response to the logout request, if single logout should be supported. For example: `https://saml2.test.de/SAML2/example.pl`. This URL can also be seen in the metadata file of the SAML2 identity provider. It is contained in the `ResponseLocation` attribute (or `Location` attribute if `ResponseLocation` is not given) of the `SingleLogoutService` tag for HTTP-Redirect binding, e. g.,
CODECODE CODExml
<ns0:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://testserver:8000/idp/saml2/slo"/>

Callback path

This path can used by the SAML2 identity provider as the destination for all requests to the service provider (including protocol, hostname, port). This is also located in the metadata generated by Get metadata.

Metadata path

This path can be used to retrieve the SAML2 metadata of this service provider (including protocol, hostname, port). The metadata is also available via the service Get metadata.

Issuer

This is the value of the Issuer attribute that is contained in the authorization request. It must match the value that has been registered with the SAML2 identity provider. This is also contained in the metadata generated by Get metadata.

Force authentication

When this check box is checked, the user must always log in with the SAML2 identity provider.

Response attribute

This name is used to grab the correct information from the authorization response to determine the login or email address of the application user. When it is a name (e. g., uid, email, mail), it matches the corresponding OID. The attributes are configured in the SAML2 identity provider and are not contained in the metadata file of the identity provider.

Signature algorithm

This field is only enabled when Certificate is set. It contains the algorithm which is used to sign requests/responses to the SAML2 identity provider.

Protocol binding

This field contains the protocol that the ID Provider should use (HTTP-POST by default). It is used for the SAML2 authorization request.

Certificate

This instance of the certificate entity, which must contain a private key, creates a digital signature for the authorization request. When this field is empty, the authorization request is not signed. The certificate content is also contained in the metadata generated by Get metadata. The authorization request is always encrypted using the algorithm as specified in Signature algorithm.

ID provider certificate

This instance of the certificate entity is used to verify the digital signature for the authorization response. When this field is empty, messages sent from the SAML2 identity provider are not checked. Only the certificate is needed; no private key is necessary. When this field is empty, there will be no check. The certificate is contained in the X509Certificate tag and may also be contained in the metadata file of the SAML2 identity provider. When you only have access to this information, you need to create a certificate file of that information using a text editor as follows:

  • Split the content into lines of length not exceeding 64 (the lines may only contain the characters from `A` to `Z`, from `a` to `z`, from `0` to `9` and `+`, `/`, `=`, which is base64 encoding).
  • Add a line just containing `-----BEGIN CERTIFICATE-----` before it and a line just containing `-----END CERTIFICATE-----` after it.
  • Then create a new instance of the certificate entity and upload the file that you just created. Digital signatures with RSA and SHA1 or SHA256 hash will be accepted.

Get metadata

This service collects the metadata as an XML file and is only available on the "Details" facet. Note that the server name, protocol, and port from the current request is used to compute the URL's.

SAML2 configuration

In most cases, all users authenticate in the same way. There is a global settings function giving the type of standard authentication:

  • Using a database if no line is defined in this setup.
  • Using a SAML2 identity provider if a SAML2 entry giving the SAML2 identity provider code is entered.
  • (and some more values).

For each user, the authentication rule can be specified as an exception (in the users definition), and the Authentication field can have the following values:

  • Standard authentication (use the default value given above).
  • Authentication using an SAML2 identity provider (the SAML2 identity provider data will be provided).
  • (and some more values).

In any case, the user has to select the correct authentication method from the log in screen.

Limitations

The current implementation does not support the following:

  • Encrypted messages.
  • Passive mode.
  • SOAP binding.
  • HTTP artifact binding.

For service provider initiated login, the identity provider must allow NameIDFormat urn:oasis:names:tc:SAML:2.0:nameid-format:transient.