Skip to main content

SSO settings reference

This topic documents the fields on the Identity Providers configuration page. Many of the fields are optional and some are set to mandatory details.

Common settings​

Although each type of provider has its own, specific configuration options, all share several common configurations.

For protocol-specific settings, see SAML 2.0 and OpenID Connect.

The following are the common configuration options:

  • Redirect URI: The endpoint hosted by Polaris where the identity provider sends information upon user sign in. Polaris populates this field for you by default.
  • Alias: A unique identifier for an identity provider. Polaris uses the alias to build redirect URIs for protocols that require a redirect URI or a callback URL to communicate with an identity provider. All identity providers must have an alias. Alias examples include facebook, google, and idp.acme.com.
  • Display Name: A friendly name for your identity provider used in the Polaris interface.
  • Enabled: Toggles the provider ON or OFF.
  • Store Tokens: When ON, Polaris stores tokens from the identity provider.
  • Stored Tokens Readable: When ON, users can retrieve the stored identity provider token.
  • Trust Email: When ON, Polaris trusts email addresses from the identity provider. If the organization requires email validation, users who sign in from this identity provider do not need to perform the email verification process.
  • Account Linking Only: When ON, Polaris links existing accounts with this provider. This provider cannot log users in, and Polaris does not display this provider as an option on the login page.
  • Hide on Login Page: When ON, Polaris does not display this provider as a login option on the login page. Clients can request this provider by using the kc_idp_hint parameter in the URL to request a login.
  • GUI order: The sort order of the available identity providers on the login page.
  • First Login Flow: The authentication flow Polaris triggers when users use this identity provider to login to Polaris for the first time.
  • Post Login Flow: The authentication flow Polaris triggers when a user finishes logging in with the external identity provider.
  • Sync Mode: The strategy to update user information from the identity provider through mappers. When choosing legacy, Polaris uses the current behavior. Import does not update user data and force updates user data when possible.

SAML 2.0​

Polaris can broker identity providers based on the SAML 2.0 protocol.

To add a SAML 2.0 identity provider, select SAML v2.0 from the Add provider list.

This section lists the SAML-specific settings.

  • Service Provider Entity ID: The unique identifier used to identify requests from a service provider. By default, this setting is set to the realm's base URL <root>/auth/realms/<realm_name>. Single Sign-On Service URL: The endpoint that starts the authentication process. The value of this field is specified by your SAML identity provider, if they publish an entity descriptor.
  • Single Logout Service URL: The SAML logout endpoint. If your SAML identity provider publishes an entity descriptor, the value of this field is specified there.
  • Backchannel Logout: Toggle this switch to ON if your SAML identity provider supports back channel logout.
  • NameID Policy Format: The URI reference corresponding to a name identifier format. By default, Polaris sets it to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
  • Principal Type: Specifies which part of the SAML assertion will be used to identify and track external user identities. Can be either Subject NameID or SAML attribute (either by name or by friendly name). Subject NameID value cannot be set together with urn:oasis:names:tc:SAML:2.0:nameid-format:transient NameID Policy Format value.
  • Allow create: Allows the external identity provider to create a new identifier to represent the principal.
  • HTTP-POST Binding Response: Controls the SAML binding in response to any SAML requests sent by an external identity provider. When OFF, Polaris uses Redirect Binding.
  • HTTP-POST Binding for AuthnRequest: Controls the SAML binding when requesting authentication from an external identity provider. When OFF, Polaris uses Redirect Binding.
  • HTTP-POST Binding Logout: When ON, Polaris responds to requests using HTTP-POST. Otherwise, HTTP-REDIRECT binding is used.
  • Want AuthnRequests Signed: When ON, Polaris uses the organization's key pair to sign requests sent to the external SAML identity provider.
  • Signature Algorithm: If Want AuthnRequests Signed is ON, the signature algorithm to use.
  • Want Assertions Signed: Indicates whether this identity provider expects a signed assertion.
  • Want Assertions Encrypted: Indicates whether this identity provider expects an encrypted assertion.
  • Force Authentication: The user must enter their credentials at the external identity provider even when the user is already logged in.
  • Validate Signature: When ON, the organization expects SAML requests and responses from the external identity provider to be digitally signed.
  • Validating X509 Certificate: The public certificate Polaris uses to validate the signatures of SAML requests and responses from the external identity provider.
  • Sign Service Provider Metadata: When ON, Polaris uses the organization's key pair to sign the SAML Service Provider Metadata descriptor.
  • Pass subject: Controls if Polaris forwards a login_hint query parameter to the identity provider. Polaris adds this field's value to the login_hint parameter in the subject of AuthnRequest so that destination providers can pre-fill their login form.
  • Allowed clock skew: Clock skew in seconds that is tolerated when validating identity provider tokens. Default is 0.

OpenID Connect​

Polaris can broker identity providers based on OpenID Connect 1.0 and Keycloak OpenID Connect.

To add an OpenID Connect identity provider, select OpenID Connect v1.0 or Keycloak OpenID Connect from the Add provider list.

This section lists the OIDC-specific settings.

  • Authorization URL: The authorization endpoint that accepts authentication requests. Through this endpoint, you can interact with the resource owner and obtain an authorization grant.
  • Pass login_hint: Passes a login hint to the identity provider.
  • Pass current locale: Passes the current locale to the identity provider as an ui_locales parameter.
  • Token URL: The token endpoint required to obtain an access token.
  • Logout URL: The logout URL endpoint in the OIDC protocol. This value is optional.
  • Backchannel Logout: A background, out-of-band, REST request to the identity provider to log out the user. Some identity providers perform logout through browser redirects only, as they may identify sessions using a browser cookie.
  • Disable User Info: Whether to use a user information service to get additional information about the user.
  • User Info URL: An endpoint the OIDC protocol defines. This endpoint points to the user profile information.
  • Environment Authentication: The environment authentication method. In the case of JWT signed with a private key, Polaris uses the organization private key. In other cases, you must define a client secret. See Client Authentication specifications for more information.
  • Environment ID: The environment identifier registered within the identity provider.
  • Environment Secret: The environment secret registered within the identity provider.
  • Environment Assertion Signature Algorithm: Signature algorithm to create JWT assertion as client authentication. In the case of JWT signed with private key or environment secret as JWT, it is required. If no algorithm is specified, the following algorithm is adapted:
    • RS256 is adapted in the case of JWT signed with private key.
    • HS256 is adapted in the case of environment secret as JWT.
  • Issuer: Polaris validates issuer claims, in responses from the identity provider, against this value.
  • Default Scopes: A list of OIDC scopes Polaris sends with the authentication request. The default value is openid. A space separates each scope.
  • Prompt: The prompt parameter in the OIDC specification. Through this parameter, you can force re-authentication and other options. See the specification for more details.
  • Accepts prompt=none forward from client: Specifies if the identity provider accepts forwarded authentication requests containing the prompt=none query parameter. If an organization receives an auth request with prompt=none, the organization checks if the user is currently authenticated and returns a login_required error if the user has not logged in. When Polaris determines a default identity provider for the auth request (using the kc_idp_hint query parameter or having a default identity provider for the organization), you can forward the auth request with prompt=none to the default identity provider. The default identity provider checks the authentication of the user there. Because not all identity providers support requests with prompt=none, Polaris uses this switch to indicate that the default identity provider supports the parameter before redirecting the authentication request. If the user is unauthenticated in the identity provider, the client still receives a login_required error. If the user is authentic in the identity provider, the client can still receive an interaction_required error if Polaris must display authentication pages that require user interaction. This authentication includes required actions (such as a password change), consent screens, and screens set to display by the first broker login flow or the post broker login flow.
  • Validate Signatures: Specifies if Polaris verifies signatures on the external ID Token signed by this identity provider. If ON, Polaris must know the public key of the external OIDC IDP. For performance purposes, Polaris caches the public key of the external OIDC identity provider. If your identity provider's private key is compromised, update your keys and clear the keys cache.
  • Use JWKS URL: This switch is applicable if Validate Signatures is ON. If Use JWKS URL is ON, Polaris downloads the identity provider's public keys from the JWKS URL. New keys download when the identity provider generates a new key pair. If OFF, Polaris uses the public key (or certificate) from its database. When the identity provider's key pair changes, import the new key to the Polaris database as well.
  • JWKS URL: The URL pointing to the location of the identity provider's JWK keys. If you use an external Polaris as an identity provider, you can use a URL such as http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs if your brokered Polaris is running on http://broker-keycloak:8180 and its realm is test.
  • Use PKCE: Uses PKCE (Proof of Key-code exchange) for identity provider brokering.
  • PKCE Method: The PKCE method to use.
  • Allowed clock skew: Clock skew in seconds that is tolerated when validating identity provider tokens. Default is 0.
  • Forwarded Query Parameters: Non OpenID Connect/OAuth standard query parameters to be forwarded to external identity provider from the initial application request to Authorization Endpoint. Enter multiple parameters separated by a comma.