External identity providers

The Identity Broker sits between the platform and external identity providers (IdPs). You connect each IdP once, in the broker. Your apps keep talking only to Access, whatever IdP the user picks.

1. 1

   The app sends the user to Access

   A normal authorization request. See How sign-in works.

2. 2

   Access or the journey sends the user to the broker

   Either Access does it directly, through an identity provider of type Identity Broker, or an Identity Orchestration journey does it, for example from a "Sign in with Google" button.

3. 3

   The broker sends the user to the external IdP

   The user authenticates there. The IdP returns to the broker's callback.

4. 4

   The broker returns the user

   It keeps only the mapped attributes and issues its own signed token. The platform, not the external IdP, is the token issuer your app sees.

5. 5

   The account is created or updated

   On first sign-in, a user is created in the Identity Store from the IdP's data (just-in-time). If updates are allowed, the data is refreshed at every sign-in.

Manage providers in the OneWelcome console under Identity broker → Identity providers. Administrators need the role_broker_write role (see Administrators and their rights).

Every provider needs the broker's callback URL registered on its side. Use your tenant host, or your custom domain if users sign in on one:

https://{tenant-host}/broker/authentication/callback

• From an OIDC provider: a client ID, a client secret (or a key, for Private key JWT) and its discovery URL (.../.well-known/openid-configuration).
• From a SAML provider: its metadata URL or XML. You give it the broker's service provider metadata after you save.
• Which attributes you need, such as email and name, and which one identifies the user. Only mapped attributes reach your apps.

1. 1

   Add identity provider → OpenID Connect

   Enter a Display name (admins see it, users don't) and optionally a Description.

2. 2

   Set Active

   Tick Active to make the provider usable on submit. Leave it off while you work on it.

3. 3

   Enter the client

   Client ID, and the Authentication method: Client secret post or basic, Client secret JWT, Private key JWT, Client TLS, or No Authentication. Enter the Client secret if the method needs one.

4. 4

   Turn on PKCE

   Recommended for every provider; required with No Authentication. Only S256 is supported.

5. 5

   Load the endpoints

   Enter the Well-known configuration endpoint and select Load. The authorization, token and user info endpoints, the issuer, the signature type and the JWKs URI are filled in. Prefer a JWKs URI over certificates: keys then rotate on their own.

6. 6

   Add a variant

   At least one. A variant is one way of asking the IdP: its Scope names, Claims and ACR values. For most social providers, one variant named e.g. authentication with scopes openid email profile is enough.

7. 7

   Map attributes

   Pick the User identifier claim (usually sub), then map each other claim you need from Claim from IDP to a OneWelcome attribute. You can rename a claim, not split or combine claims. Unmapped claims are dropped.

8. 8

   Submit

   Submit makes it available. Save draft keeps an unfinished version hidden from users.

To propagate logout to the IdP, tick Single logout and enter its End session endpoint URI.

1. 1

   Add identity provider → SAML

   Display name, optional Domain aliases and description, Active.

2. 2

   Give the IdP metadata

   Dynamic from URL: enter the Metadata URL and select Load; the entity IDs and Preferred binding fill in. Or Static XML: paste the metadata and set the entity IDs and binding (HTTP Post or Artifact) yourself. Static metadata doesn't update: renew its certificates by hand before they expire.

3. 3

   Keys

   Select or upload the signing key pair the broker signs requests with; the broker generates one if you don't. Tick Encrypted assertion to have personal data encrypted to you, and Enable Mutual TLS if the IdP requires it for the back channel. Add a next key pair before the current one expires, to rotate without downtime.

4. 4

   Add a variant

   Set the Authentication context class reference (ACR) the IdP should use and the comparison (Exact, Minimum, Better, Maximum). Prefer Exact or Minimum. Tick Force authentication to make the IdP ask again even if the user has a session there.

5. 5

   Map attributes and submit

   Map each assertion attribute to a OneWelcome attribute, then Submit.

6. 6

   Give your metadata to the IdP

   After saving, open the provider's View details. The broker shows its service provider metadata URLs. Send them to the IdP.

Each variant gets an ACR value, shown in the provider's details under Variants. It has the form urn:onewelcome:broker:v1:<provider-alias>:<variant-alias>. That value is how a sign-in picks the provider.

• Use the alias the broker returns, not the display name. The broker derives it (lower case, no accents or punctuation) and adds a number if it is taken.
• An explicit ACR value wins over login_hint. A hint that matches no alias, or a provider with more than one variant, fails.
• Button text comes from the journey or login page. Button colors and logos come from the brand's theme. Follow each provider's branding rules.

Test every provider end to end before you add it to a production app. Use a dedicated test web client and any OAuth test tool that supports the authorization code flow with PKCE.

1. 1

   Create a test identity provider in Access

   Type Identity Broker, enabled, not default.

2. 2

   Create a test web client

   Client secret, grant Authorization code, the test tool's callback as Redirect URL, Default scope openid, the test identity provider under user registration, consent page skipped.

3. 3

   Configure the test tool

   Discovery URL https://{tenant-host}/oauth/.well-known/openid-configuration, the test client's ID and secret, PKCE on.

4. 4

   Run the flow with the ACR value

   Set acr_values to the variant's ACR value. You should land on the external IdP's sign-in page.

5. 5

   Sign in and redeem the code

   You should come back to the tool and get an access token and an ID token.

6. 6

   Check the ID token

   Decode it. The mapped attributes should be there, with the names you mapped them to.

7. 7

   Clean up

   Delete the test web client, or remove its redirect URL, when you're done.

To manage providers from a pipeline, use the Identity Broker API. Reads never return secrets, and an update replaces the whole configuration.