Manage SAML 2.0 Identity Providers

This section includes instructions to manage SAML 2.0 identity providers.

Watch to see how to manage SAML 2.0 compliant identity providers (5:01).

See:

Currently, in the Identity & Access Management Portal, you can only add SAML 2.0 identity providers through a manual configuration. To add a SAML 2.0 identity provider with auto-discovery through a metadata URL, contact Customer Support. Future plans for the portal include a self-service feature that enables you to add SAML 2.0 identity providers by importing a metadata file or with auto-discovery through a metadata URL.

Add a SAML 2.0 Identity Provider

  1. On the Manage Identity Providers page, click the Add SAML Provider button.

  2. Complete the following fields. You can hover over the information icons for instructions as you complete each field.

    TIP: If you have a metadata file, you can copy and paste the information directly in the Identity Provider Entity ID, Single Sign-on Endpoint, and X509 Certificate fields.

    • Name (required): Enter a name for the identity provider (for example, MY IDP US). This name will be displayed in the External Authentication Provider options in System > Security > Users > <user>. Each identity provider name must be unique.

    • Scheme (required): A scheme is automatically generated in OneStream, but you can edit it. Each identity provider scheme must be unique and should be alphanumeric with no spaces. The scheme is used in the assertion consumer service (ACS) URL and service provider entity ID URL. For example:

      • Scheme: MYIDPUS

      • ACS URL: www.applicationname.com/OneStreamIS/federation/MYIDPUS/signin-saml

      • Service provider entity ID URL: www.applicationname.com/OneStreamIS/federation/MYIDPUS/saml

      IMPORTANT: If you include special characters in the scheme, it may cause an issue in the ACS URL and service provider entity ID URL. Enter a scheme that is alphanumeric with no spaces.

    • Identity Provider Entity ID (required): Enter the entity ID from the identity provider. It is a unique identifier for the identity provider that is used to validate incoming SAML responses and assertions. It should be entered in a URI format (for example, https://identityprovider.com/entityid). If possible, copy and paste the identity provider entity ID directly from the identity provider to ensure the value is an exact match.

    • Single Sign-on Endpoint (required): Enter the single sign-on endpoint from the identity provider (for example, https://login.sso.example.com). The single sign-on endpoint is a URL that is used by the service provider to initiate the login process. Authentication requests are sent to the single sign-on endpoint. If possible, copy and paste the single sign-on endpoint directly from the identity provider to ensure the value is an exact match.

    • X509 Certificate (required): Enter the X509 certificate from the identity provider. It is a public key that is used to validate incoming SAML responses and assertions. If possible, copy and paste the X509 certificate directly from the identity provider to ensure the value is an exact match.

    • Include Custom Claims (optional): Claims are properties about the user sent from the identity provider. Select this option to use a custom claim identifier for authentication. If you select this option, enter the custom claims in the field in a comma-separated value (CSV) format (for example, uniqueID,email). Custom claims can use letters, numbers, and special characters. Custom claims cannot have spaces. Claims are searched in the order they are entered in the field.

      Advanced Settings

    • Require Signed Assertion (optional): This option indicates if assertions in an incoming sign-on response must be signed. When you select this option, the sign-on response validation will fail if the response does not contain signed assertions.

    • Require Encrypted Assertion (optional): This option indicates if assertions in an incoming sign-on response must be encrypted. When you select this option, the sign-on response validation will fail if the response does not contain encrypted assertions. If selected, upload the certificate used to encrypt assertions. Ensure the certificate is valid; an expired certificate will cause authentication to fail.

    • Encryption Certificate Password (required if using an encryption certificate that is password protected): Enter the password for the encryption certificate. Characters entered in the field are masked for security.

    • Sign Authentication Requests (optional): When you select this option, the service provider will always sign generated requests. If selected, upload the signing certificate, which is used to sign generated requests. Ensure the certificate is valid; an expired certificate will cause authentication to fail.

    • Signing Certificate Password (required if using a signing certificate that is password protected): Enter the password for the signing certificate. Characters entered in the field are masked for security.

  3. Click the SAVE button.

  4. Click the COPY buttons to copy the ACS URL and the service provider entity ID URL displayed in the message to configure on the external IdP. Both of these values are case sensitive. So, the capitalization has to match between the values configured in OneStream IdentityServer and the external identity provider.

    The ACS URL directs the identity provider where to send its SAML response after authenticating a user. Some IdPs also refer to this URL as a recipient URL or destination URL. A service provider entity ID is typically a URL or URI that is assigned to the entity, and it is used to identify the entity in SAML messages and metadata. Some IdPs also refer to this URL as an audience URL.

  5. Test the identity provider to ensure the authentication method is valid. See Test a SAML 2.0 Identity Provider.

    IMPORTANT: Test the identity provider configuration each time you add or edit an identity provider to ensure the authentication method is valid.

Test a SAML 2.0 Identity Provider

You can test a SAML 2.0 identity provider to ensure the authentication method is valid.

  1. On the Manage Identity Providers page, find the identity provider to test.

    NOTE: You can only test identity providers that are enabled.

  2. Click the TEST button in the row for the identity provider. If the test is successful, it will walk you through the login process. You will need to enter your credentials for the external IdP.

  3. Return to the OneStream Identity Management tab in your browser to view the test results. The results indicate if the:

    • Identity provider has been configured correctly.

    • User profile exists in OneStream.

    • User is assigned to the identity provider.

    • Authentication requests are signed.

    • Assertions are encrypted.

    • Assertions are signed.

    If the test is not successful, resolve the issue. See Resolve Common Issues when Testing SAML 2.0 Identity Providers. Contact Customer Support if needed.

  4. Close the tab.

Resolve Common Issues when Testing SAML 2.0 Identity Providers

This section describes how errors display and how to resolve common issues that can occur when testing SAML 2.0 identity providers.

Incorrect Identity Provider Entity ID

This error typically indicates that the identity provider entity ID is set incorrectly for the identity provider. To resolve this issue, update the identity provider entity ID entered in the Identity & Access Management Portal to match the identity provider entity ID in the metadata file downloaded from the external identity provider. See Edit a SAML 2.0 Identity Provider.

Incorrect Certificate

This error typically indicates that the certificate entered in the Identity & Access Management Portal does not match the certificate that is being used by the external identity provider. To resolve this issue, copy the certificate from the metadata file and paste it into the X509 Certificate field for the identity provider in the Identity & Access Management Portal to ensure the value is an exact match. See Edit a SAML 2.0 Identity Provider.

Expired Certificate

This error indicates that the encryption certificate or signing certificate in the Identity & Access Management Portal is expired. To resolve this issue, upload a valid certificate in the Identity & Access Management Portal. See Edit a SAML 2.0 Identity Provider.

Incorrect ACS URL or Service Provider Entity ID URL

This is an example of an error that can occur if the ACS URL or the service provider entity ID URL is incorrect (for example, the capitalization is incorrect). Since this error comes from the identity provider, it can look different depending on which identity provider you use. For this type of error, more information can typically be found in the logs from the external identity provider.

To resolve any errors related to the ACS URL or the service provider entity ID URL, copy both values directly from the Identity & Access Management Portal and configure them inside the identity provider. Both of these values are case sensitive. So, the capitalization has to match between the values configured in OneStream IdentityServer and the external identity provider. Specifically, note the capitalization in the OneStreamIS part of the value. See Add a SAML 2.0 Identity Provider and View Details of a SAML 2.0 Identity Provider.

Single Sign-on Endpoint Access Blocked

This is an example of an error that displays when a firewall prevents OneStream IdentityServer from accessing the single sign-on endpoint. To resolve this error, contact your IT department to ensure that OneStream IdentityServer can access this URL.

User Does not Exist in OneStream

This test result indicates that the authentication with the external identity provider was successful. However, there is no user in OneStream that matches the claim. Typically, this indicates that the user does not exist in OneStream. To resolve this issue, log into OneStream and create the user. See How Users are Configured for Authentication.

Another possibility is that the claim received from the identity provider does not match the External Provider User Name of the user in OneStream. If that is the case, either create a custom claim for the identity provider so that the correct user name is being used to look up the OneStream user (see Edit a SAML 2.0 Identity Provider) or change the External Provider User Name in the user profile in System > Security > Users > <user> (see How Users are Configured for Authentication).

User not Assigned to Identity Provider

This test result indicates that the authentication with the external identity provider was successful and that there is a user in OneStream that matches the claim value that was received from the identity provider. However, this user has not been assigned to the correct authentication provider in OneStream. To resolve this issue, assign the user to the correct External Authentication Provider in the user profile in System > Security > Users > <user>. See How Users are Configured for Authentication.

View Details of a SAML 2.0 Identity Provider

  1. On the Manage Identity Providers page, find the identity provider.

  2. Click the VIEW button in the row for the identity provider.

  3. You can click the COPY button to copy the ACS URL and service provider entity ID URL to configure on the external IdP.

    The ACS URL directs the identity provider where to send its SAML response after authenticating a user. Some IdPs also refer to this URL as a recipient URL or destination URL. A service provider entity ID is typically a URL or URI that is assigned to the entity, and it is used to identify the entity in SAML messages and metadata. Some IdPs also refer to this URL as an audience URL.

  4. You can click the EDIT button to edit the identity provider. See Edit a SAML 2.0 Identity Provider.

    IMPORTANT: Editing identity provider information may affect the ability to log in for configured users.

  5. Click the CANCEL button to return to the Manage Identity Providers page.

Edit a SAML 2.0 Identity Provider

  1. On the Manage Identity Providers page, find the identity provider to edit.

    NOTE: You cannot edit an identity provider if you are logged in with it.

  2. Click the EDIT button in the row for the identity provider.

    IMPORTANT: Editing identity provider information may affect the ability to log in for configured users.

  3. Edit the information. See Add a SAML 2.0 Identity Provider.

    NOTE: Select Enable Identity Provider to enable the identity provider. Clear the check box to disable the identity provider. If you disable an identity provider, it may affect the ability to log in for configured users. An identity provider cannot be disabled if a configured user is logged in with the identity provider.

    NOTE: You can edit all fields except the ACS URL and the service provider entity ID URL. These fields can be copied but cannot be edited.

  4. Click the SAVE button.

  5. Click the OK button to confirm.

  6. If the scheme was updated, click the COPY buttons to copy the updated ACS URL and service provider entity ID URL displayed in the message to configure on the external IdP. Both of these values are case sensitive. So, the capitalization has to match between the values configured in OneStream IdentityServer and the external identity provider.

    The ACS URL directs the identity provider where to send its SAML response after authenticating a user. Some IdPs also refer to this URL as a recipient URL or destination URL. A service provider entity ID is typically a URL or URI that is assigned to the entity, and it is used to identify the entity in SAML messages and metadata. Some IdPs also refer to this URL as an audience URL.

    IMPORTANT: Because the scheme is used in the ACS URL and service provider entity ID URL, if you update the scheme, you must copy the updated ACS URL and service provider entity ID URL to configure on the external IdP.

  7. Test the identity provider to ensure the authentication method is valid. See Test a SAML 2.0 Identity Provider.

    IMPORTANT: Test the identity provider configuration each time you add or edit an identity provider to ensure the authentication method is valid.

Remove a SAML 2.0 Identity Provider

  1. On the Manage Identity Providers page, find the identity provider to remove.

  2. Click the REMOVE button in the row for the identity provider.

    IMPORTANT: An identity provider cannot be removed if users are configured to it. Remove the identity provider as an authentication method from any configured users before removing it.

  3. Click the OK button to confirm. Once the identity provider is removed, it will no longer appear on the Manage Identity Providers page.