Topics in this chapter include:
The Oracle Identity Cloud Integrator provider combines authentication and identity assertion into a single provider. The provider establishes identity (the Subject) on WebLogic Server with the authenticated user, the user's groups, and the user's application roles when the identity store is the Oracle Identity Cloud Service.
The Oracle Identity Cloud Service provides identity management, single sign-on, and identity governance for applications on-premise, in the cloud, or on mobile devices. It leverages OAuth 2.0 for authorization of custom applications and OpenID Connect to externalize authentication using federated single-sign-on. For details about the Oracle Identity Cloud Service, see http://docs.oracle.com/en/cloud/paas/identity-cloud/index.html.
You can use the Oracle Identity Cloud Integrator provider with the Oracle Identity Cloud Service as described in the following sections.
Basic Authentication
With basic authentication, the server requests a user name and password from the client and verifies that the user name and password are valid by comparing them against the authorized users in the Oracle Identity Cloud Service. Using basic authentication, users in an Oracle Identity Cloud Service tenant can log into the WebLogic Server Administration Console, use the WebLogic Scripting Tool (WLST), or log into an application running on WebLogic Server.
The provider supports identity domains, which are used to represent the tenancy of users and groups. The term tenant is a synonym for identity domain; an identity domain represents one tenant of a multitenant system. The Oracle Identity Cloud Integrator provider can authenticate users across any identity domain. In the provider, the Any Identity Domain Enabled attribute is always set to true. For more information about identity domains, see Configuring Security in Using Oracle WebLogic Server Multitenant.
Perimeter Authentication
The concept of perimeter authentication is the process of authenticating the identity of a remote user outside of the application server domain. Perimeter authentication is typically accomplished by the remote user specifying an asserted identity and some form of corresponding proof material, which extends the single sign-on concept all the way to the perimeter. The Oracle Identity Cloud Integrator provider supports perimeter authentication from users authenticated in the Oracle Identity Cloud Service using the following perimeter authentication mechanisms:
OpenID Connect Identity (ID) tokens created by the Oracle Identity Cloud Service. The identity asserter handles the idcs_user_assertion HTTP header for Oracle Identity Cloud Service identity tokens by default. The user assertion (ID token) represents a user authenticated by the Oracle Identity Cloud Service and is used to map to a WebLogic Server subject containing principals with the user, group, and Oracle Identity Cloud Service application roles information.
This functionality includes a new IDCSAppRole principal. See weblogic.security.principal in Java API Reference for Oracle WebLogic Server.
Also, a new weblogic.entitlement.rules.IDCSAppRoleName () predicate was added that can be used in role mapping and authorization policies.
The REMOTE_USER HTTP header for Oracle Identity Cloud Service protected resources. The REMOTE_USER header handles users that were validated by Oracle Identity Cloud Service policy protection using the HTTP Basic header and then sent to the server using the REMOTE_USER HTTP header.
In addition to setting the REMOTE_USER using an HTTP header, the Oracle Identity Cloud Service also specifies the user tenancy using an HTTP header.
When Oracle Identity Cloud Service indicates that the anonymous user is accessing the service, WebLogic Server denies access to protected Java EE resources.
Oracle Identity Cloud Service access tokens for protected resources. The access token is a credential that allows an OAuth client to access a protected resource and is used to map to a WebLogic Server Subject containing principals using the user, group, Identity Cloud Service application roles, scopes, and audience information based on the token. The provider supports access tokens using the Authorization token type and retrieves the access token from the Authorization HTTP header.
This functionality includes two new principals, IDCSScope and IDCSClient, to support storing client and scope information in the subject. The Oracle Identity Cloud Service audience (IDCSAudience) is optionally stored in the public credentials of the subject. See weblogic.security.principal and Class IDCSAudience in Java API Reference for Oracle WebLogic Server.
A new weblogic.entitlement.rules.Scope () predicate was added that can be used in role mapping and authorization policies.
The REMOTE_USER and Authorization HTTP headers are not enabled by default. The REMOTE_USER header is not enabled by default because this header should only be sent by a trusted client. You cannot have any publicly accessible endpoints if REMOTE_USER is enabled on the Oracle Identity Cloud Integrator provider. When exposing both public and protected endpoints, then use of REMOTE_USER may leave applications and WebLogic Server open to security vulnerabilities. The Authorization HTTP header is not enabled by default because the services must be protected by the Oracle Identity Cloud Service to safely accept user information from access tokens.
If required, you must enable the Authorization and REMOTE_USER HTTP headers in the WebLogic Server Administration Console using the Active Types setting on the Common page for the provider or using WLST. See Enabling Authorization and REMOTE_USER Header Support: Main Steps.
To control access token processing, you can set additional configuration attributes such as AudienceEnabled and ClientAsUserPrincipalEnabled, and access token claim attributes on the Provider Specific page, or directly on the MBeans. Details about these attributes are provided in Oracle Identity Cloud Integrator Provider: Provider Specific in Oracle WebLogic Server Administration Console Online Help.
Programmatic Identity Assertion
The Oracle Identity Cloud Integrator provider can be used for programmatic assertion from an OpenID Connect ID token obtained from the Oracle Identity Cloud Service. In this scenario, the application logic implements the OAuth protocol (for example, the authorization code grant flow) to obtain an ID token from Oracle Identity Cloud Service. After obtaining the ID token, the application logic uses the WebLogic Server Authentication API to assert the Oracle Identity Cloud Service user identity from the ID token. See the following specifications and API reference documents:
weblogic.security.services.Authentication in Java API Reference for Oracle WebLogic Server
In addition, the provider can be used to validate an Oracle Identity Cloud Service user when using Oracle Platform Security Services (OPSS), Oracle Web Services Manager (OWSM), or SSO mechanisms such as SAML2.0.
Multiple Identity Store Environment
You can use the Oracle Identity Cloud Integrator provider to access the Oracle Identity Cloud Service as a single source of users, or in a hybrid environment in combination with other identity stores. As part of the WebLogic Security Framework, the Oracle Identity Cloud Integrator provider can be configured with other authentication providers in the security realm so that each provider can authenticate users in its respective identity store. For example, you can configure the Default Authenticator provider to authenticate users in the embedded LDAP server, and the Oracle Identity Cloud Integrator to authenticate users in the Oracle Identity Cloud Service. When you configure multiple Authentication providers, use the JAAS Control Flag for each provider to control how the Authentication providers are used in the login sequence. See Using More Than One Authentication Provider.
If the Oracle Identity Cloud Integrator provider is the only authentication provider configured in the security realm, an Oracle Identity Cloud Service user can boot WebLogic Server. To do so, the Oracle Identity Cloud Service user must be added to a group or granted a role that is assigned to the WebLogic Server Admin role. Otherwise, WebLogic Server cannot be booted. If the Oracle Identity Cloud Integrator provider fails to connect to the Oracle Identity Cloud Service, or throws an exception, make sure the configuration settings are set correctly for this provider.
Additionally, if you are setting up a single sign-on configuration, for example using SAML 2.0, you can configure the Oracle Identity Cloud Integrator provider as the authentication provider to validate the user. See Configuring Single Sign-On with Web Browsers and HTTP Clients Using SAML.
Oracle Identity Cloud Service Single Sign-On (SSO) and Logout Synchronization
When you have established your identity using the basic, perimeter, or programmatic authentication mechanisms, the provider includes an SSO synchronization filter to synchronize the Oracle Identity Cloud Service SSO session with the local container session. The SSO synchronization filter is an implementation of the Servlet Filter. The filter intercepts each request to the container and determines whether to act on the request based on certain HTTP headers that are part of the request. The job of the filter is to ensure that the user identity in the container (tenant and user name) matches the identity of the SSO session. If the identities match, the session continues. If there is a mismatch in identities (for example a user has logged out or a session timed out), the filter invalidates the container's user session and performs a redirect to continue.
The synchronization filter is enabled by default. You can adjust the settings, if desired, in the Synchronization Filter section on the Provider Specific page in the WebLogic Server Administration Console or by setting them on the MBeans. Details about these attributes are provided in Oracle Identity Cloud Integrator Provider: Provider Specific in Oracle WebLogic Server Administration Console Online Help.
For WebLogic Server to authenticate users with the Oracle Identity Cloud Service, the Oracle Identity Cloud Integrator provider must be associated with an OAuth client that is registered with the Oracle Identity Cloud Service. The OAuth client allows the provider access to the Oracle Identity Cloud Service.
Before you can configure the provider you must obtain the required OAuth client information from the Oracle Identity Cloud Service. To do so, you create a trusted application in the Oracle Identity Cloud Service Console. A trusted application in the Oracle Identity Cloud Service is a type of custom application that can be accessed by multiple users and hosted in a secure and protected place (server) where the trusted application uses OAuth 2.0. Because you know where the application is hosted, you can treat that application as trusted. Creating the application in Oracle Identity Cloud Service results in the provisioning of an OAuth client.
Creating the OAuth Client: Main Steps
To create the OAuth client in the Identity Cloud Service Console:
Log into the Identity Cloud Service console as the Tenant Administrator.
Create a trusted application. See Adding a Trusted Application in Administering Oracle Identity Cloud Service.
Note that the OAuth client can be used only within the specific tenant in which it was provisioned.
In the Add Trusted Application wizard:
Enter a client name and, optionally, a description.
Select only Client Credentials as the allowed grant type. This setting is used when the authorization scope is limited to the protected resources under the control of the client or to the protected resources registered with the authorization server. The client presents its own credentials to obtain an access token.
Assign the client to the Identity Domain Administrator application role. To do so, select Grant the client access to Identity Cloud Service Admin APIs and then, in the box that is displayed, select Identity Domain Administrator.
Using the Identity Domain Administrator application role provides write access to the Oracle Identity Cloud Service user store. The WebLogic Server Oracle Identity Cloud Integrator provider does not support any update operations. Therefore, you must use the Identity Cloud Service Administration Console to modify the content of the user store.
Step through the remaining pages in the wizard and click Finish. Record the Client ID and Client Secret that are displayed when you create the application. You need these values when you configure the Oracle Identity Cloud Integrator provider. The attributes that you must provide when configuring the provider are described in Required Configuration Attributes.
Activate the application.
Required Configuration Attributes
To configure the Oracle Identity Cloud Integrator provider in WebLogic Server, you must provide the following attributes from the OAuth client:
Tenant — Name of the primary tenant in the Oracle Identity Cloud Service where you provisioned the OAuth client.
ClientId — The OAuth client ID used to access the Oracle Identity Cloud Service identity store.
ClientSecret — The OAuth Client Secret (password) used to generate access tokens.
Client tenant (Optional) — Name of the OAuth client tenant in which the Client Id resides. This attribute is not required if the Client tenant is the same as the primary tenant.
The attributes required to configure the connection are described in Prerequisites for Configuring the Oracle Identity Cloud Integrator Provider. You also need to provide the Oracle Identity Cloud Service Host and Port where the Oracle Identity Cloud Service is accessible. This value for the host is the base name for the Identity Cloud Service Tenant URLs (for example identity.host.com) and does not include the tenant name. If TLS/SSL is enabled, be sure to use the secure port.
Details about additional configuration attributes for the provider are described in Oracle Identity Cloud Integrator Provider: Provider Specific in Oracle WebLogic Server Administration Console Online Help.
The main steps for configuring the provider using the WebLogic Server Administration Console are as follows:
Select Security Realms>realm-name>Providers>Authentication, and select New.
In the Create a new Authentication Provider page, enter a name for the provider, then select OracleIdentityCloudIntegrator from the Type menu, and click OK.
Select the provider, then the Provider Specific page, and configure the required attributes to connect to the Oracle Identity Cloud Service.
If TLS/SSL is required, select SSLEnabled.
Click Save.
See Configure Oracle Identity Cloud Integrator provider in Oracle WebLogic Server Administration Console Online Help.
Configuring the Oracle Identity Cloud Integrator Provider: WLST Online Example
You can configure the Oracle Identity Cloud Integrator Provider using WLST online in script mode by creating and executing a script that adds the provider to the security realm and configures the connection to the Oracle Identity Cloud Service.
To do so, create a WLST script, similar to the sample IdentityCloudIntegrator.py script shown in Example 20-1.
In the script, replace the required variables idcsHost, idcsPort, clientTenant, clientID, and clientSecret with the appropriate values for your environment. In the connect command in the script, replace the username, password, and host:port with the values for the server in the domain to which you are adding the provider. Execute the script as described in Using the WebLogic Scripting Tool in Understanding the WebLogic Scripting Tool
This script starts WLST online, adds the provider to the security realm, sets the provider configuration, sets the JAAS control Flag, and activates the changes.
You need to restart the server after updating the domain.
Example 20-1 Sample IdentityCloudIntegrator.py WLST Script
Note:
For clarity, this WLST example script shows the username and password in clear text. However, you should avoid entering clear-text passwords in WLST commands in general, and you should especially avoid saving on disk WLST scripts that include clear-text passwords. In these instances you should use a mechanism for passing encrypted passwords instead.#
# Use appropriate Oracle Identity Cloud Service host, port, client tenant, client Id, and client secret.
#
idcsHost="identity.host.com"
idcsPort=443
clientTenant="myTenant"
clientId="123456789"
clientSecret="987654321"
#
# Start WLST edit session
#
connect("username","password","t3://host:port")
edit()
startEdit()
#
# Add the Oracle Identity Cloud Integrator provider to the security realm configuration where the Default
# Authenticator is the only existing authentication provider.
#
realm = cmo.getSecurityConfiguration().getDefaultRealm()
atn = realm.lookupAuthenticationProvider('IdentityCloudServiceIntegrator')
if atn == None:
atn = realm.createAuthenticationProvider('IdentityCloudServiceIntegrator','weblogic.security.providers.authentication.OracleIdentityCloudIntegrator')
#
# Setup the Oracle Identity Cloud Integrator provider configuration
#
atn.setHost(idcsHost)
# Example host requires SSL. Comment out next line if using an Oracle Identity Cloud Service instance that does not require SSL.
atn.setSSLEnabled(true)
atn.setPort(idcsPort)
atn.setTenant(clientTenant)
# If the Client Tenant == Tenant then no need to set the Client Tenant value
atn.setClientTenant(clientTenant)
atn.setClientId(clientId)
atn.setClientSecret(clientSecret)
atn.setControlFlag('SUFFICIENT')
#
# Adjust the JAAS control flag for the DefaultAuthenticator such that users from the embedded LDAP server or the
# Oracle Identity Cloud Service are allowed to log into WebLogic Server.
#
atnDefault = realm.lookupAuthenticationProvider('DefaultAuthenticator')
if atnDefault != None:
atnDefault.setControlFlag('SUFFICIENT')
#
# Activate changes
#
activate()
exit()
#
# Restart WebLogic Server
#Configuring the Oracle Identity Cloud Integrator Provider: WLST Offline Example
You can configure the Oracle Identity Cloud Integrator provider using WLST offline by executing a series of commands that add the provider to the security realm and configure the connection to the Oracle Identity Cloud Service.
For details about using WLST offline, see Using WLST Offline to Update an Existing WebLogic Domain in Understanding the WebLogic Scripting Tool.
Executing these commands edits the domain as follows:
Opens the domain configuration for editing. Be sure to replace the variables domainDirName and DOMAIN_NAME with the appropriate values for your environment. For example, if you accepted the default values when you created the domain, domainDirName is ORACLE_HOME/user_projects/domains/base_domain and DOMAIN_NAME is base_domain. Also be sure to provide the actual name of the security realm. In this example we used myrealm .
Adds the Oracle Identity Cloud Integrator provider to the security realm configuration where the Default Authenticator is the only existing authentication provider
Configures the connection to the Oracle Identity Cloud Service using the values you provide for idcsHost, idcsPort, clientTenant, clientID, and clientSecret.
Adjusts the JAAS control flag for the DefaultAuthenticator such that users from the embedded LDAP server or the Oracle Identity Cloud Service are allowed to log into WebLogic Server.
Updates and closes the domain, and exits WLST offline.
Example 20-2 WLST Offline Commands to Configure Oracle Identity Cloud Integrator Provider
readDomain('domainDirName')
cd('SecurityConfiguration/DOMAIN_NAME/Realm/myrealm')
create('IdentityCloudServiceIntegrator','weblogic.security.providers.authentication.OracleIdentityCloudIntegrator','AuthenticationProvider')
cd('AuthenticationProviders/IdentityCloudServiceIntegrator')
# Execute the set commands needed to configure the Oracle Identity Cloud Integrator provider host, port, tenant,
# client tenant, client id, client secret and JAAS control flag.
idcsHost="identity.host.com"
idcsPort=443
clientTenant="myTenant"
clientId="123456789"
clientSecret="987654321"
# Set attributes
set("Host",idcsHost)
set("SSLEnabled", true)
set("Port", idcsPort)
set("Tenant", clientTenant)
set("ClientTenant", clientTenant)
set("ClientId", clientId)
set("ClientSecretEncrypted", clientSecret)
set("ControlFlag", "SUFFICIENT")
# Set any other authenticators to SUFFICIENT. In this example, set the JAAS control flag for the DefaultAuthenticator
# such that users from the embedded LDAP server or the Oracle Identity Cloud Service are allowed to log into WebLogic Server.
cd("..")
cd("DefaultAuthenticator")
set("ControlFlag", "SUFFICIENT")
updateDomain()
closeDomain()
exit()The Oracle Identity Cloud Integrator provider supports one-way SSL. To secure the connection using TLS/SSL, you need to establish trust between WebLogic Server and the Oracle Identity Cloud Service. To do so, you may need to obtain the Oracle Identity Cloud Service SSL certificate and import it into the WebLogic Server trust store.
Note:
If the Oracle Identity Cloud Service uses a well-known certificate authority (CA) such as Symantec, and your WebLogic domain is using Java Standard Trust, WebLogic Server trusts it by default and importing the certificate is not required. If, however, your domain is configured for custom trust, you may need to import the certificate into your trust store, regardless of whether the Oracle Identity Cloud Service is using a well-known CA.When you enable FIPS mode for WebLogic Server and have configured the Oracle Identity Cloud Integrator provider, Java SSL Context initialization exceptions may occur, or users from Oracle Identity Cloud Service may fail to authenticate. These issues may be the result of your system using the default Java system truststore where the CA certificates store, cacerts, is not FIPS compliant.
When you enable JDK debug (-Djavax.net.debug=ssl), error messages for the exception are similar to the following:
Default SSLContext initialization Key Store: Key Store type: jks Initializing key managers Exception while initializing default context JKS keystores cannot be loaded in FIPS-140 mode. Only PKCS12 PBES2 key stores are supported
If you are using a PKCS12 keystore that is not FIPS compliant (created with the keytool command using the Sun JSSE provider for example), you may also receive an error similar to the following when using the keytool command:
keytool error: java.lang.SecurityException: Algorithm not allowable in FIPS140 mode: PBE/PKCS12/SHA1/RC2/CBC/40
To address these errors and allow WebLogic Server to operate successfully, you need to first convert the JDK keystore to a FIPS compliant PKCS12 keystore, and then set the Java system properties to update the Java default settings for the truststore used with the default SSL Context. For details, see Converting the Default JKS Keystore for FIPS Compliance.
The Oracle Identity Cloud Integrator provider supports Oracle Identity Cloud Service access tokens via the Authorization HTTP header, and users validated by the Oracle Identity Cloud Service via the REMOTE_USER HTTP header.
Topics in this section include:
The Authorization and REMOTE_USER HTTP headers are not enabled by default. The services must be protected by Oracle Identity Cloud Service to safely accept user information from access tokens and from HTTP headers that contain no proof or signing materials. Therefore, you must enable the support for these headers before they can be accepted.
Note:
Use caution before enabling the REMOTE_USER HTTP header. This header should only be sent by a trusted client. You cannot have any publicly accessible endpoints ifREMOTE_USER is enabled on the Oracle Identity Cloud Integrator provider. When exposing both public and protected endpoints, then use of REMOTE_USER may leave applications and WebLogic Server open to security vulnerabilities.Only Oracle Identity Cloud Service identity tokens, idcs_user_assertion and Idcs_user_assertion, active types are accepted by default. To enable Authorization and REMOTE_USER HTTP header support:
Enable the Authorization header and/or the REMOTE_USER header in the WebLogic Server Administration Console using the Active Types setting on the Common page for the provider, or using WLST as shown in this example. Note that you can enable these headers individually as required by your environment.
connect("username", "password", "t3://host:port")
edit()
startEdit()
realm = cmo.getSecurityConfiguration().getDefaultRealm()
atn = realm.lookupAuthenticationProvider('IdentityCloudServiceIntegrator')
atn.setActiveTypes(["idcs_user_assertion","REMOTE_USER","Authorization"])
activate()
disconnect()
exit()
#
# Restart WebLogic Server
#To ensure that the process ordering for the multiple token types is defined, set the precedence order on the RealmMBean to specify the ordering for the different HTTP headers. See Ordering of Identity Assertion Headers.
When an HTTP request is processed by the WebLogic Server container, there may be multiple matches that can be used for identity assertion. Headers passed to the Oracle Identity Cloud Integrator provider may contain an Oracle Identity Cloud Service identity token, Oracle Identity Cloud Service access token, or REMOTE_USER. However, the provider can only consume one active token type at a time. As a result there is no way to provide a set of tokens that can be consumed with one call. Therefore, the WebLogic Server container must choose between multiple tokens to perform identity assertion.
If you have enabled the REMOTE_USER or Authorization active types, you also need to update the IdentityAssertionHeaderNamePrecedence property on the RealmMBean to set the precedence order for the different HTTP headers, otherwise it is undefined.
Table 20-1 highlights some basic use cases and examples for precedence ordering in each case.
Table 20-1 HTTP Header Precedence Ordering for Different Use Cases
| Use Case | Precedence Ordering | Comments |
|---|---|---|
|
HTTP request may contain all supported tokens/headers |
Authorization: Bearer (access token) idcs_user_assertion ( identity token) REMOTE_USER |
Settting this ordering gives precedence to claims from Identity Cloud Service tokens first. If no Identity Cloud Service tokens are supplied, then authentication falls back to using only remote user information. Oracle Identity Cloud Service tokens are not provided when the Oracle Identity Cloud Service handles basic authentication and then sends the |
|
HTTP requests contain primarily access tokens and HTTP Basic authentication with some Web single sign-on (SSO) tokens |
Authorization: Bearer (access token) REMOTE_USER |
In some cases additional security context may be required, such as the scopes from the access token. When additional information is required, then access and identity tokens should take precedence over remote user information. Setting this ordering gives precedence to access tokens and establishes a security context that includes user, client, application roles, scopes and audience data from the access token. For Web SSO and HTTP basic credentials that have been verified by the Oracle Identity Cloud Service, the deployed application uses the remote user information established in the security context, including the user's Identity Cloud Service application roles. Note: When Oracle Identity Cloud Service identity tokens are included, the remote user information is still preferred and the user's Identity Cloud Service application roles are still obtained. |
|
HTTP requests may contain multiple tokens but remote user should take precedence |
REMOTE_USER |
If the service wants to use just the remote user information, setting remote user as the highest precedence ensures that HTTP requests that contain Note: When using the<auth-method>CLIENT-CERT, BASIC</auth-method> to define an authentication mechanism for the application, the remote user information is still preferred over the Authorization: Basic credential because CLIENT-CERT is the first method used for authentication by the Web Container. Therefore, the HTTP BASIC credential is only processed if the assertion from the remote user information (tokens) fails or the token related HTTP headers are omitted from the HTTP request. See Providing a Fallback Mechanism for Authentication Methods in Developing Applications with the WebLogic Security Service. |
Setting HTTP Header Precedence: WLST Example
You can use WLST online to set the HTTP Token precedence order as shown here. This example sets the ordering to authorization (access token), identity token, and then remote user as shown in the first use case.
connect("username", "password", "t3://host:port")
edit()
startEdit()
realm = cmo.getSecurityConfiguration().getDefaultRealm()
realm.setIdentityAssertionHeaderNamePrecedence(["Authorization: Bearer","idcs_user_assertion","REMOTE_USER"])
activate()
disconnect()
exit()
#
# It is not necessary to restart the server.
#