SAML service provider configuration
The OneWelcome Identity Platform can act as a SAML service provider during user authentication. For this reason, the OneWelcome Identity Platform exposes metadata at the metadata URL. You can configure the values used in the metadata for this service provider.
To configure SAML service provider usage, oo the administration console, go to the Configuration section , select System, and then select the SAML Service provider tab.
The image below shows the SAML Service provider view on the admin console with an example configuration.
SAML velocity log file
To configure the location of the SAML velocity log file, use the following field:
| Field name | Default value | Description |
|---|---|---|
| Velocity log location | /tmp/velocity.log | Storage location in the file system for the velocity log file that is generated by the SAML module. |
After you change this value, the OneWelcome Identity Platform engine application must be restarted.
SAML service provider metadata
You can configure the following metadata for the SAML service provider:
| Field name | Default value | Description |
|---|---|---|
| SAML Service Provider enabled | true | Indicates whether the SAML endpoints on the OneWelcome Identity Platform are enabled. If these endpoints aren't enabled, the samlUserAuthenticator cannot be used. |
| Entity ID | oneginiTokenServerEntityId | Entity identifier of the SAML service provider |
| Unique Entity ID per Client | false | When enabled, an identifier is appended to the previously defined 'entityId' on a per-mobile app or -web client basis. The metadata endpoint changes to include the identifier. The identifier is case sensitive. |
| ID | oneginiTokenServer | Identifier of the SAML Service Provider. |
| Validity | 1 | Indicates the validity of the SAML service provider metadata in days. |
| Language | en | Language code used in the descriptions, and so on, in the SAML service provider metadata. |
| Organization name | Onegini | Name of the organization used in the SAML service provider metadata. |
| Support contact name | Support | Name of the support contact person used in the SAML service provider metadata. |
| Support contact email | support@onegini.com | The email address of the contact person in the SAML service provider metadata. |
Metadata URL
By default the metadata URL is /oauth/saml/metadata. If Unique Entity ID per Client is enabled, this URL does not work. It needs to include an additional identifier. For mobile applications, it is the application identifier. For web clients, it is the client ID.
| Metadata URL | Unique entity ID per client enabled |
|---|---|
/oauth/saml/metadata |
false (default) |
/oauth/saml/{identifier}/metadata |
true |
The defined URL for an application with the identifier oneginiExampleApp is: /oauth/saml/oneginiExampleApp/metadata. The identifier is case-sensitive.
The generated metadata XML includes the entity ID, a dash, and the client identifier. If the base EntityID is defined as exampleEntityId and the SAML metadata for an application has the identifier oneginiExampleApp, the combined entityId in the XML is exampleEntityId-oneginiExampleApp.
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="someId" entityID="exampleEntityId-oneginiExampleApp" validUntil="2018-05-11T13:27:07.028Z">
...
</md:EntityDescriptor>
Configure SAML requests signing
To configure SAML requests signing set the following fields:
| Field name | Required | Format | Default value | Description |
|---|---|---|---|---|
| Private key | yes | PEM encoded PKCS #1 or PKCS #8 RSA Private Key | empty | The private key used by the SAML service provider to sign requests. |
| Certificate | yes | PEM encoded X.509 certificate | empty | The certificate of the SAML service provider that can be used by the IDP to validate the signature. |
The following code snippet generates PKCS #1 and the associated certificate using OpenSSL:
openssl genrsa -out prv-pkcs1.pem 2048
openssl req -new -x509 -key prv-pkcs1.pem -out x509-cert.pem
The following code snippet generates PKCS #8 and the associated certificate using OpenSSL:
openssl genpkey -out prv-pkcs8.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048
openssl req -new -x509 -key prv-pkcs8.pem -out x509-cert.pem
For convenience, the private key and certificate can be also generated by the OneWelcome Identity Platform using the Generate signing credentials button.
SAML assertion encryption
When the OneWelcome Identity Platform acts as a SAML service provider, it may advertise additional public keys that can be used later by an external SAML identity provider to encrypt the assertion.
Because the SAML assertion carries user-specific sensitive information, it is a good practice to enable the assertion encryption functionality to keep that data safe.
| Field name | Required | Format | Default value | Description |
|---|---|---|---|---|
| Assertion encryption enabled | no | empty | Enables or disables SAML assertion encryption functionality. | |
| Private key | yes if encryption is enabled | PEM encoded PKCS #1 or PKCS #8 RSA Private Key | empty | The private key used by the SAML service provider to decrypt assertions returned by the SAML identity provider. |
| Certificate | yes if encryption is enabled | PEM encoded X.509 certificate | empty | The public key or certificate of the SAML service provider that can be used by the IDP to encrypt the assertion. |
SAML binding
By default, the OneWelcome Identity Platform uses the following order to resolve the SAML binding during authentication:
- Artifact
- POST
- Redirect
There may be reasons for disabling certain bindings or changing the preferred order for choosing a binding. For example, this might happen when both the OneWelcome Identity Platform and the SAML identity provider support artifact binding but cannot communicate with each other due to network restrictions.
| Field name | Required | Default value | Description |
|---|---|---|---|
| Enabled bindings | yes | Artifact, POST, Redirect | Enables or disables SAML bindings for authentication |
| Preferred order | no | Artifact, POST, Redirect | Changes the order in which the enabled SAML bindings are resolved during authentication |
Single logout
The goal of the single logout (SLO) feature is to log out the user from a web client when their SAML session is terminated by the SAML identity provider. To configure using SLO, use the following fields:
