How To: Connect an External SAML or OIDC Identity Provider to SecureAuth CIAM With Just-in-Time Provisioning

Version Affected: All

 

Overview

This article explains how to connect an external SAML or OpenID Connect (OIDC) identity provider (IdP) to a SecureAuth CIAM workspace or organization, map the attributes it sends, and create users in an identity pool when they first sign in, using Just-in-Time (JIT) provisioning. The external IdP can be a partner company's IdP, Microsoft Entra ID, Google, or a SecureAuth Identity Platform realm.

Before you start, you need administrator access to the SecureAuth CIAM workspace or organization that users will sign in to, an identity pool to create the users in, and administrator access to the external IdP, so that SecureAuth CIAM can be registered there as a SAML service provider or an OIDC client.

An attribute passes through four stages before it reaches a user's profile or tokens: the provider connection, the provider's attribute list, the mapping into the authentication context, and the JIT provisioning mapping. The authentication context is the set of user attributes that SecureAuth CIAM builds for each sign-in. Tokens, JIT provisioning and policies read from it, not from the raw SAML assertion or ID token, so an attribute that misses any stage is silently dropped.

 

In this article

• Step 1: Connect the Identity Provider
• Step 2: Add the Attributes the Identity Provider Sends
• Step 3: Map the Attributes to the Authentication Context
• Step 4: Turn On Just-in-Time Provisioning
• Step 5: Test the Sign-In and Check the Mapping Results

Step 1: Connect the Identity Provider

Create the connection in the SecureAuth CIAM workspace or organization that users will sign in to. Use a provider-specific template when one exists, such as SecureAuth Workforce, Microsoft Entra ID or Google, and the generic SAML or OIDC template for any other provider.

For a SAML identity provider:

1. Go to Authentication > Providers and click Create Connection.
2. In Third-Party Providers, select the SAML template and click Next.
3. Enter a name for the connection. SecureAuth CIAM uses this name to build the connection's Entity ID.
4. Copy the Entity ID and the ACS URL (Assertion Consumer Service URL), and use them to register SecureAuth CIAM as a service provider at the external IdP.
5. Add the external IdP's metadata: fetch it from the IdP's metadata URL, upload the metadata file, or paste the raw XML. If metadata is not available, enter the IdP's Sign-in URL and its IDP certificate instead.
6. Under Identifier source, select Subject to take the user's identifier from the assertion's Subject, or select Attribute and enter the attribute's name in Identifier attribute.
7. Click Save.

A SAML connection does not require the external IdP to allow SecureAuth's IP addresses. The SAML request and response travel through the user's browser, so SecureAuth CIAM makes no server-to-server call to the IdP. The exception is metadata fetched from a URL: SecureAuth CIAM downloads it directly, so the host serving the metadata must accept requests from the SecureAuth SaaS platform.

For an OIDC identity provider:

1. At the external IdP, create an OIDC application that uses the authorization code flow and requests the openid, email and profile scopes.
2. In SecureAuth CIAM, go to Authentication > Providers, click Create Connection, select the provider's template or the generic OIDC template, and click Next.
3. Copy the Redirect URL shown on the form and add it as a redirect URI on the IdP's application.
4. Enter the IdP's bare issuer address as the Issuer URL, for example https://login.example.com, without /.well-known/openid-configuration on the end. It must exactly match the issuer value in the IdP's discovery document.
5. Enter the Client ID and the client secret from the IdP's application. For Microsoft Entra ID, enter the secret's Value, not its Secret ID.
6. Click Save.

SecureAuth CIAM can authenticate to the IdP's token endpoint with either client_secret_basic or client_secret_post. Client secrets expire at most IdPs, Microsoft Entra ID included, and an expired secret stops every sign-in through the connection. Record the expiry date and replace the secret at the IdP and on the connection before it lapses.

Step 2: Add the Attributes the Identity Provider Sends

SecureAuth CIAM only reads the attributes listed on the connection's Attributes tab. Add every attribute the IdP sends that you want to use.

1. Go to Authentication > Providers and open the connection.
2. Open the Attributes tab and click Add attribute.
3. Enter the attribute's name exactly as the IdP sends it, including its case. Choose a data type that matches the value: a string for a single value, or a string array for a value the IdP sends as a list.
4. Repeat this for each attribute, then save the connection.

Some SAML attribute names contain dots, such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. Enter these exactly as they appear in the assertion. The current SAML connector, shown as saml_v2 in audit logs, escapes the dots itself, so typing a backslash before each dot escapes them twice and the attribute is never found. Older SAML connections needed each dot escaped with a single backslash, so remove those backslashes when you copy a mapping from an older connection to a new one.

Step 3: Map the Attributes to the Authentication Context

Every attribute that tokens, JIT provisioning or policies need must be mapped into the authentication context. Always map the user's email address. JIT provisioning needs an identifier to create or match the user, and an administrator who signs in to the SecureAuth CIAM admin portal through the connection is shown as Profile when no email address reaches the authentication context.

1. If the authentication context has no attribute to receive a value, go to Authentication > Settings > Attributes, click Create Attribute, enter a name, data type and description, and click Create.
2. Go to Authentication > Providers, open the connection, and select Mappings.
3. For each attribute, choose the source attribute from the connection and the target authentication context attribute.
4. Click Save mappings.

A mapping cannot change the IdP subject, which always holds the identifier that the external IdP issued. If applications need a different subject, such as the user's email address, set it for the whole workspace: under OAuth > Tokens > Subject identifier for OIDC applications, or under SAML > General > NameID Value for SAML applications. Because this is a workspace-wide setting, every IdP connected to the workspace must put that attribute into the authentication context.

Step 4: Turn On Just-in-Time Provisioning

1. Go to Authentication > Providers, open the connection, and select the Provisioning tab.
2. Select the Just-in-Time Provisioning card and choose the identity pool that new users are created in.
3. Under Identifier Correlation, select the incoming attribute, for example Email, and the identity pool identifier it matches: Email, Phone, Username or External ID. SecureAuth CIAM uses this to link the sign-in to an existing user before it creates a new one.
4. Review the attribute provisioning rows. Email, first name and last name are mapped by default. For each further attribute, click Add row, choose the source attribute from the authentication context, and choose the identity pool attribute it fills.
5. Make sure every attribute that the identity pool's schema marks as required has a row, and that the external IdP sends a value for it. To give a row a fallback, click Set default value.
6. To control whether an attribute is overwritten each time the user signs in, use the three-dot menu on its row to turn on or off attribute updates on each sign-in.
7. Click Save.

To fill a business metadata attribute, set the target to business_metadata.<attribute>, not user.business_metadata.<attribute>. The target's data type must match the incoming value: a single string from the IdP cannot fill a string array attribute.

Step 5: Test the Sign-In and Check the Mapping Results

1. Start a sign-in from the application, or from the organization's sign-in page, and choose the new connection. Always start at SecureAuth CIAM: it creates the sign-in session before it sends the user to the IdP, and a response that arrives without that session is rejected.
2. Sign in at the external IdP with a test user whose mapped attributes all have values.
3. In SecureAuth CIAM, open the workspace's Audit Logs and filter them by the connection's ID.
4. Open the login_accepted event and check idp_mapping_details. Each mapping shows "result": "mapped" when its value arrived, or "result": "missing" when it did not.
5. Confirm that the user was created in the identity pool with the expected identifiers and attributes.

Special Considerations

Just-in-Time provisioning has no approval step. Every user the external IdP authenticates is created in the identity pool and can reach the workspace's applications. Limit who can sign in at the external IdP, for example by assigning its application only to the right group, or apply an access policy to the workspace or application.

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.