OIDC Authentication Realm

< Previous		Next >

Overview

The OpenID Connect (OIDC) authentication realm allows authentication with an OIDC provider. OIDC is an identity layer on top of the OAuth 2.0 protocol, which allows single sign-on for clients to verify your identity based on the authentication performed by an authorization server. The following identity providers are supported:

Auth0
Google Identity Platform
Microsoft Azure Active Directory

An OIDC realm configuration is specified in an OIDCAuthenticationRealm root object in the security configuration type.

OIDC is only supported via the HTTP protocol; non-HTTP communication is not supported. The StreamBase OIDC implementation only supports authentication, and not authorization. Each OIDC realm configuration must specify a fallback realm that is used for all authorization and for authentication from clients that are not using HTTP. That fallback realm must exist when the OIDC realm is activated or activation fails.

Required Properties

OIDC requires at least one identity provider configuration. For each identity provider:

documentDiscoveryUrl: A URL used to retrieve information about the identity provider.
clientId: The OIDC client's authentication ID.
clientSecret: The OIDC client's authentication secret key, optionally encrypted with epadmin encrypt secret.
identityAttributeName: The attribute in an authenticated user's JSON web token (JWT) that identifies a user name that can be mapped to a set of roles in the fallback realm for authorization purposes.

OIDC Authentication Realm

The OIDCAuthenticationRealm root configuration object defines OpenId Connect authentication for a node. Figure 1, “OIDCAuthenticationRealm relationships” shows the relationships to other configuration objects.

OIDCAuthenticationRealm relationships

A detailed description of the configuration object properties is in OIDCAuthenticationRealm object properties and a snippet for these properties is in Example 1, “OIDCAuthenticationRealm object snippet”.

OIDCAuthenticationRealm object properties

Name	Type	Description
`defaultRedirectURL`	String	The default address to redirect a user to after authentication if no redirect URL was provided in the authentication request. Optional. Default value is null.
`identityProviders`	Associative array of `OIDCIdentityProvider` configuration objects keyed by identity provider names.	An associative array of `OIDCIdentityProvider` (see OIDCIdentityProvider object properties) configuration objects indexed by provider names. Provider names must be URL safe and non-empty. Required.
`fallbackAuthenticationRealmName`	String	The name of the realm used for all authorization. This must be the name of an active `LDAPAuthenticationRealm` or `LocalAuthenticationRealm`. If the fallback realm is not defined, configuration activation will fail. Required.
`name`	String	Name of the authentication realm. This name must be unique across all authentication realms. Required.
`pendingAuthenticationTimeoutSeconds`	Integer	The amount of time to wait for a provider's response in seconds before timing out. Optional. Default is 300 seconds.
`requireTrustedHostMembership`	Boolean	A value of `true` only allows users to connect from a trusted host, a value of `false` allows users to connect from any host. Optional. Default value is `false`.

Example 1. OIDCAuthenticationRealm object snippet

name = "oidc-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    OIDCAuthenticationRealm =
    {
        name = "my-oidc-authentication-realm"
        requireTrustedHostMembership = false
        defaultRedirectURL = "http://redirect.acme.com"
        fallbackAuthenticationRealmName = "my-ldap-realm"
        pendingAuthenticationTimeoutSeconds = 600
        identityProviders =
        {
            "Google" = { ... }
            "Auth0" = { ... }
        }
    }
}

OIDC Identity Provider Configuration

The OIDCIdentityProvider object defines the configuration for OpenId Connect providers.

Support is provided for federated identity providers like Auth0. Federated providers use subject prefixes to map to the actual provider defined in this configuration. This mapping is configured using the subjectProviderMappings configuration property. For example:

//
//    Subject provider mappings in Auth0 configuration
//    A subject prefix of google-oauth2 maps to the 
//    configured "Google" identity provider
//
subjectProviderMappings =
{
    "google-oauth2" = "Google"
}

//
//    Auth0 identity contains "sub" claims
//
//    The "|" is the delimiter, so "google-oauth2" is the prefix that 
//    identifies the actual provider providing the identity information.
//    105569619522230371597 is the subject for the principal from the identity 
//    provider represented by google-oauth2
//
sub: 'google-oauth2|105569619522230371597'

//
//    The same principal authenticated directly against "Google"
//    would have the same identity information in the "sub" field.
//
sub: '105569619522230371597'

Figure 2, “OIDCIdentityProvider relationships” shows the relationships to other configuration objects.

OIDCIdentityProvider relationships

A detailed description of the configuration object properties is in OIDCIdentityProvider object properties and a snippet for these properties is in Example 2, “OIDCIdentityProvider object snippet”.

OIDCIdentityProvider object properties

Name	Type	Description
`clientID`	String	The client's authentication identifier. Required
`clientSecret`	String	The client's authentication secret key. Opaque passwords are generated using the `epadmin secret` target. See epadmin-secret(1). Required.
`documentDiscoveryURL`	String	The identity provider's Document Discovery URL for obtaining discovery information. Required.
`identityAttributeName`	String	The attribute in a given principal's ID Token to be used as the identity for this principal. Required.
`subjectProviderMappings`	Associative array of subject prefixes to identity provider names.	Map federated identity provider subject prefixes to configured identity provider names. The provider names must be configured in this configuration. This field is only valid for federated identity providers like Auth0. Optional. Default is `null` (no mappings).

Example 2. OIDCIdentityProvider object snippet

name = "oidc-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    OIDCAuthenticationRealm =
    {
        identityProviders =
        {
            "Google" =
            {
                documentDiscoveryURL = "https://accounts.google.com/.well-known/openid-configuration"
                clientID = "my-google-client-identifier"
                clientSecret = "my-google-client-secret"
                identityAttributeName = "email"
            }
            "Auth0" =
            {
                documentDiscoveryURL = "https://tibco.auth0.com/.well-known/openid-configuration"
                clientID = "my-auth0-client-identifier"
                clientSecret = "my-auth0-client-secret"
                identityAttributeName = "email"
                subjectProviderMappings =
                {
                    "google-oauth2" = "Google"
                }
            }
        }
    }
}