Configure custom identity providers (IdPs) for SAML or OIDC single sign-on so that your organization's users can authenticate with their existing corporate credentials.

Note:

Identity provider management is available to Enterprise plan admins only.

Configure a custom identity provider (IdP) to enable single sign-on (SSO) for your organization. When an IdP is configured, users are redirected to it for authentication when they log in to IBM Bob across the IDE, Bob Shell, and Bob Web.

Bob supports SAML and OpenID Connect (OIDC) identity providers. Use the protocol that matches your organization's identity platform.

Supported identity provider types

IBM Bob supports the following SSO protocols:

SAML (Security Assertion Markup Language)

OIDC (OpenID Connect)

Note:

Auth0 and Keycloak are the currently verified and supported OIDC identity providers. Other OIDC providers might work if they meet Bob's configuration and token requirements, but they are not currently verified.

Adding an identity provider

Adding an IdP is a two-step process. First, you configure the IdP and save it. Then you add the email domains that use it.

Step 1: Configure the identity provider

Go to the IBM Bob Administration page.

Select the Authentication tab.

Click Add IdP.

Enter a name for the IdP.

Select the IdP type: SAML or OIDC.

Generate your service provider (SP) credentials.

Bob requires an SP private key and SP certificate to sign SAML authentication requests. You must generate these yourself using the openssl command-line tool.

Note:

If you already have an SP key pair and certificate, skip to the next step.

Run the following command to generate the SP private key:

openssl genrsa -out sp_private_key.pem 2048

Then run this command to generate the SP certificate from the private key. Replace the /CN, /O, and /C values with a descriptive certificate name, your organization name, and your two-letter country code:

openssl req -new -x509 -key sp_private_key.pem -out sp_certificate.pem -days 365 -subj "/CN=Bob SAML SP/O=IBM/C=US"

Note:

The sp_certificate.pem file must also be uploaded to your IdP so it can verify signatures on requests from Bob.

Enter the configuration details for the IdP.

Review the protocol-specific requirements in the following sections.

Click Save.

The IdP is created and appears in the table on the Authentication tab.

SAML configuration

SAML requires the following configuration details:

Identity provider fields — obtain these from your IdP:

idp_entity_id — the unique identifier for the IdP (for example, https://idp.example.com)

idp_sso_url — the SSO URL where Bob sends authentication requests

idp_certificate — the PEM-encoded X.509 certificate used to verify SAML responses from the IdP

Service provider fields — use the files generated in the previous step:

sp_private_key — the contents of sp_private_key.pem

sp_certificate — the contents of sp_certificate.pem

Optional fields:

idp_slo_url — the IdP's Single Logout URL. Single Logout is not yet fully implemented in Bob.

In the Attribute mapping section, map the IdP's user attributes to IBM Bob's user fields. The mapping format is Bob attribute name → IdP attribute name or URI. Check your IdP configuration for the correct attribute names.

email (required) — the user's email address

name (optional) — the user's full display name

given_name (optional) — the user's first name

family_name (optional) — the user's last name

groups (optional) — the user's groups

IDP administrator: registering a new OIDC client

Before a Bob instance admin can configure an OIDC IdP record in Bob, an IdP administrator must first create an OIDC application (client) inside the identity provider. The values produced by this step are what the Bob instance admin supplies when adding the IdP in Bob.

Application and grant type

Create a Web application (server-side / confidential client) in your identity provider and enable the Authorization Code grant type. Bob uses the Authorization Code flow exclusively — do not select Implicit, Device Code, or Client Credentials.

Redirect URI

Register the following callback URL in the OIDC application. Most providers perform a strict string match, so copy it exactly:

https://api.us-east.bob.ibm.com/authn/v1/auth/callback

Scopes to enable on the client

Scope	Purpose	Required
`openid`	Enables OIDC mode and returns an `id_token`	Yes
`email`	Exposes the user's email address in the `id_token` or via the userinfo endpoint	Yes
`offline_access`	Grants a `refresh_token` alongside the access token	Yes for most providers

Bob requires a refresh_token to be present in every authorization-code exchange response. If your provider issues refresh tokens via a different mechanism (for example, a provider-specific scope, or unconditionally on every code exchange), configure accordingly — but ensure the client is allowed to receive refresh tokens. If no refresh_token is returned, the login is aborted.

Token endpoint authentication method

Configure the token endpoint authentication method on the OIDC application to client_secret_post. Bob sends client_id and client_secret as form body parameters on every token request. client_secret_basic, private_key_jwt, and none are not currently supported.

Token settings

Setting	Required value
Access token format	Any (JWT or opaque — Bob does not parse the IdP access token directly)
ID token	Must be issued on every authorization-code exchange and every token refresh
ID token signing algorithm	`RS256`, `ES256`, or `PS256`
Refresh token rotation	Supported. Bob stores the new token on each renewal. If your provider rotates refresh tokens, ensure the previous token is invalidated only after Bob receives the replacement (standard rotation behavior, not one-time-use with no grace window).

Values to hand to the Bob instance admin

Once the client application is created, provide the following values to the Bob instance admin:

Value	Where to find it	Bob configuration field
Client ID	Application credentials page	`client_id`
Client Secret	Application credentials page	`client_secret`
Authorization Endpoint URL	Provider's OIDC endpoints page or `.well-known/openid-configuration`	`authorization_endpoint`
Token Endpoint URL	Provider's OIDC endpoints page or `.well-known/openid-configuration`	`token_endpoint`
JWKS URI	Provider's OIDC endpoints page or `.well-known/openid-configuration`	`jwks_uri`
Issuer URL	Provider's OIDC endpoints page or `.well-known/openid-configuration`	`issuer`
Userinfo Endpoint URL (optional)	Provider's OIDC endpoints page or `.well-known/openid-configuration`	`userinfo_endpoint`

Tip:

Most providers publish all endpoint URLs at https://<your-provider-domain>/.well-known/openid-configuration.

OIDC configuration

Bob supports OIDC provider discovery. You can use the Retrieve configuration button in the UI to auto-populate the endpoint fields from your provider's .well-known/openid-configuration document, or you can enter each endpoint URL manually.

OIDC requires the following configuration details:

Field	Required	Description
`client_id`	Yes	The client identifier registered with your identity provider.
`client_secret`	Yes	The client secret for the registered application. Bob stores this securely and never returns it in API responses.
`scopes`	Yes	The scopes requested during the authorization flow. This list must include `openid`. It usually also includes `email` and the provider-specific scope used to issue a refresh token, such as `offline_access`.
`authorization_endpoint`	Yes	The HTTPS authorization URL that Bob redirects users to for sign-in.
`token_endpoint`	Yes	The HTTPS token URL used to exchange the authorization code for tokens.
`jwks_uri`	Yes	The HTTPS URL of the JSON Web Key Set (JWKS) used to verify the signature of `id_token` responses.
`issuer`	No	The HTTPS issuer identifier for the identity provider.
`prompt`	No	The OIDC `prompt` value forwarded to the authorization request.

OIDC does not use Attribute mapping. Bob reads the user's email directly from the email claim in the id_token.

OIDC example configuration

{
  "authorization_endpoint": "https://corp.okta.com/oauth2/default/v1/authorize",
  "token_endpoint": "https://corp.okta.com/oauth2/default/v1/token",
  "issuer": "https://corp.okta.com/oauth2/default",
  "client_id": "0oa1b2c3d4e5f6g7h8i9",
  "client_secret": "super-secret-value",
  "scopes": ["openid", "email", "offline_access"]
}

OIDC requirements and limitations

Bob requires a refresh_token in the authorization code exchange response. If your provider does not return one, login fails.

For most providers, adding offline_access to scopes is what triggers refresh token issuance. Some providers use different behavior, so check your provider's documentation.

OIDC back-channel logout is not supported.

If your provider changes its endpoint URLs, update the IdP configuration in Bob.

Step 2: Add domain filters

After the IdP is saved, add the email domains that should use it for authentication.

On the Authentication tab, locate the IdP you just created and open its settings.

In the Domain filters section, add the email domains that should use this IdP. Users whose email addresses match a configured domain are redirected to this IdP at login.

Save your changes.

Note:

Each email domain can only be associated with one IdP. If a domain is already in use by another IdP, the configuration cannot be saved until the conflict is resolved. Each domain must also be verified before SSO is enforced. See Verifying domain ownership.

Verifying domain ownership

IBM Bob requires you to verify that your organization owns each domain before SSO is enforced for it. Verification is done by adding a DNS TXT record to your domain.

Go to the IBM Bob Administration page.

Select the Authentication tab.

Select the IdP that contains the domain you want to verify.

In the Domain filters section, locate the domain and copy the verification code shown.

In your DNS provider, add a TXT record to the domain with the following format:

bob-verify=<verification-code>

Replace verification-code with the code copied from the Domain filters section.

Return to the Authentication tab and click Check verification for the domain.

The domain verification status updates to Verified when IBM Bob successfully detects the TXT record. DNS changes can take time to propagate.

Removing an identity provider

Go to the IBM Bob Administration page.

Select the Authentication tab.

Locate the IdP you want to remove and click Delete.

In the confirmation dialog, click Confirm.

Warning:

Deleting an IdP removes the SSO configuration for all associated domains. Users who relied on that IdP for authentication will need to log in through another method. A warning is shown if the IdP has verified domains.

Managing identity providers

Supported identity provider types

Adding an identity provider

Step 1: Configure the identity provider

SAML configuration

IDP administrator: registering a new OIDC client

Application and grant type

Redirect URI

Scopes to enable on the client

Token endpoint authentication method

Token settings

Values to hand to the Bob instance admin

OIDC configuration

OIDC example configuration

OIDC requirements and limitations

Step 2: Add domain filters

Verifying domain ownership

Removing an identity provider

On this page