6 Configuring a Mobile Security Access Server Instance

This chapter describes how to configure identity store profiles, trusted issuers and DNs, message security, policy access, and authentication endpoints and other security settings for a Mobile Security Access Server (MSAS) instance. You can perform this configuration using either the MSAS console component of the OAM console or WLST. Both methods are described. It also provides advanced configuration procedures for Kerberos, MSAS as a WebGate, and MSAS SSO, and OAuth2 client configuration.

Topics include:

6.1 Understanding MSAS Instance Configuration

The Mobile Security Manager provides the capability for an administrator to configure and manage MSAS instances from a central location using the MSAS Instance Configuration page in the MSAS console component of the OAM console. From this page you can create identity store profiles, configure trusted issuers and message security settings, cache refresh rates, and authentication endpoints such as KINIT/PKINIT and OAuth2 confidential and mobile clients. You can also configure various system settings such as outbound message settings, proxy server settings, and logging, and others.

WLST commands also provide the ability to configure an MSAS instance from the command line or using scripts. For details about using the WLST commands, see "Configuring an MSAS Instance Using WLST".

When you create an MSAS instance using the configMSAS script or the MSAS console, a default configuration document is created in the repository that contains all of the properties valid for the instance with their default values. When you modify the default configuration as described in this chapter, this configuration document is updated with the changes. For details about creating an MSAS instance using the configMSAS script, see "Configuring an MSAS Instance" in Installing Oracle Mobile Security Access Server.

The configuration performed using the MSAS console pages or the WLST commands applies at the logical instance level only. Any configuration defined for the instance is shared by all physical instances bound to the logical instance.

In most cases, changes made to the Mobile Security Access Server configuration do not require a server restart. By default, the changes are synchronized with the server using a user-defined polling interval, that you can specify using the cache refresh property. For details about setting this cache refresh property, see "Configuring the Cache Refresh Time" and "Configuring the Cache Refresh Time Using WLST". If you want these changes to go into effect immediately, you can use the synchronize feature as described in "Synchronizing MSAS Instance Configuration".

In certain situations, however, such as creating an identity store profile, changes to the configuration do require a server restart. Table 6-1 lists the types of configuration updates that require you to restart the MSAS server.

Table 6-1 Configuration Changes that Require an MSAS Server Restart

Configuration Update Additional information

Creating or editing an identity store profile

"Configuring the Identity Store Profile"

"Configuring an Identity Store Profile Using WLST"

Changes to SSL keystore and truststore

"Configuring the SSL Keystore and Truststore"

"Configuring SSL Settings Using WLST"

Setting outbound connection pool and HTTP(s) connection properties

"Configure Outbound Message Settings"

"Configuring Outbound Message Settings Using WLST"

Setting outbound proxy server settings

"Configure Proxy Server Settings"

"Configuring Proxy Server Settings Using WLST"

6.2 Configuring an MSAS Instance Using the MSAS Console

You manage the configuration of an MSAS instance using the MSAS Instance Configuration page. From this page you can view general configuration information about the instance, configure identity store profiles, define trusted issuers, configure keystore aliases and message settings, configure cache management, configure authentication endpoints, and other system settings.

The following sections describe how to configure an MSAS instance using the different tabs on the MSAS Instance Configuration page:

6.2.1 Viewing General MSAS Instance Configuration

The General tab of the MSAS Instance Configuration page provides basic information about the instance such as instance name and display name, description, the URL of the physical MSAS instance to which this logical instance is bound, the number of URLs and applications in the instance, and version data. You can modify the display name and the description for the instance. It also provides version information for the configuration.

To view general information about the instance:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

    3. In the MSAS Environments page, click MSAS or Instances in the MSAS tile. The MSAS Instances Summary page opens in a new tab.

      The first 8 instance in the environment are displayed. Click Show More to show additional instances.

    4. If necessary, use the Search field to refine the list of instances or to locate a specific instance. Enter all or part of a name in the Search field and press the search icon

    5. In the MSAS Instances Summary page, click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. In the MSAS Instance Configuration page, click the General tab to view the basic information about the instance.

    Field Description
    Name MSAS Instance ID. This field is read-only.
    Display Name Meaningful name used to identify the instance. This field is editable.
    Description Description of the instance. This field is editable.
    MSAS URLs Host and port of the physical MSAS instances to which this logical instance is bound. A logical MSAS instance can be bound to more than one physical instance.
    Stats Number of URLs and Applications configured in the instance.
    Version Information Version number of the instance, including the last user to update it and when it was updated.

6.2.2 Configuring the Identity Store Profile

The Identity Store Profiles tab of the MSAS Instance Configuration page provides the ability to add an identity store profile to the MSAS instance, edit an existing profile. delete a profile, and set the default.

An identity store profile is a logical representation of a user repository. All user and group entities are present in this identity store. There can be multiple profiles associated with an MSAS instance, and one profile can be marked as the default against which all authentication and user profile queries will occur.

Note:

You can also configure identity store profiles using WLST as described in "Configuring an Identity Store Profile Using WLST".

The identity store configuration is stored in an Identity Profile Document in the MSAS Repository.

To configure an identity store profile:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

    3. In the MSAS Environments page, click MSAS or Instances in the MSAS tile. The MSAS Instances Summary page opens in a new tab.

      The first 8 instance in the environment are displayed. Click Show More to show additional instances.

    4. If necessary, use the Search field to refine the list of instances or to locate a specific instance. Enter all or part of a name in the Search field and press the search icon

    5. In the MSAS Instances Summary page, click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. In the MSAS Instance Configuration page, click the Identity Store Profiles tab.

  3. To add an identity profile, click Add.

    To edit an existing identity profile, click Edit. Note that if you are editing an existing profile, the fields are prepopulated with the configuration information for the existing profile.

    The Identity Store Profile page displays, as shown in Figure 6-1

    Figure 6-1 Identity Store Profile Page

    Description of Figure 6-1 follows
    Description of "Figure 6-1 Identity Store Profile Page"

  4. In the Identity Store Profile page, enter a meaningful name and description in the Name and Description fields.

  5. In the Directory Information section, set the directory type, host name, and credential details for the identity store. When you have completed all the fields, click Test Connection to test the connection to the directory.

    If the connection to the identity store fails, ensure that the values you provided are correct. If the identity store is configured on an SSL port, verify that the SSL truststore contains the trusted SSL certificate. If necessary, you can import this trusted certificate as described in "Configuring the SSL Keystore and Truststore".

    Field Description
    Directory Type Select one of the following directory types from the menu:

    • Active Directory

    • OID (Oracle Internet Directory)

    • ODSEE (Oracle Directory Server Enterprise Edition)

    • OUD (Oracle Unified Directory)

    • WLS-LDAP (Embedded LDAP in WebLogic Server)
    Host Name Host name of the server running the selected directory.
    Port Port used to access the selected directory.
    SSL If connecting using an SSL port, select this control to enable SSL.
    Trust Store Type For Mobile Security Access Server, the supported trust store type is KSS. This field is read only
    Trust Store Path Fully qualified path to the trust store. By default, this path is kss://msas_id/ssltruststore, where msas_id is the MSAS ID of the instance with which this identity store profile is associated. This field is read only.
    Bind DN DistinguishedName (DN) of the user to connect to the directory.
    Bind Password/Confirm Password Bind password for the Bind DN to connect to the selected directory.
    Base DN LDAP Searchbase under which all users and groups are located in the LDAP directory. For example, cn=us, dn=mycompany, dc=com

  6. In the User section, set the user names, base DN, and object classes for the identity store profile.

    Field Description
    Base DN Container under which the users exist. For example, cn=users,dn=mycompany,dc=com.
    Login ID Attribute Login ID for the user. Typically this is uid or mail attribute in the LDAP. In Active Directory, this refers to the UserPrincipalName.
    Object Classes Fully qualified names of the schema classes used to represent users. By default, this field is set to the standard LDAP objectclass inetOrgPerson.

    To add an object class, click Add, then enter the value in the Object Class Name field.

    To remove an object class, select the row containing the class to be removed then click Remove.

  7. In the Group section, set the group names, base DN, and object classes for the identity store profile.

    Field Description
    Base DN Searchbase for the group entries in the LDAP directory. For example, cn=group,dn=mycompany,dc=com.
    Group Name Attribute Attribute that uniquely identifies the name of the group or role. For example, cn.
    Object Classes Fully qualified names of the schema classes used to represent groups. By default, this refers to the LDAP standard objectclass of groupofuniquenames. In Active Directory this is group.

    To add an object class, click Add, then enter the value in the Object Class Name field.

    To remove an object class, select the row containing the class to be removed then click Remove.

  8. When you have completed all of the fields, click Save.

  9. If you have configured more than one identity store profile, select the profile to use as the default. To do so, select the profile in the table and click Set as default. When set, all authentication and user profile queries will occur against the default identity store profile.

    Note:

    When you configure the identity store for an MSAS instance using the idmConfig tool with the -configOMSS mode=OMSAS arguments, the identity store that is created automatically becomes the default. To use an identity profile created as described in this section as the default profile, you must set it as described in this step.

  10. Click Apply.

  11. Restart the MSAS server.

6.2.3 Configuring Trusted Issuers and DN Lists for Signing Certificates

The Authentication tab of the MSAS Instance Configuration page enables you to define SAML and JWT trusted issuers and a list of trusted distinguished names (DNs) for SAML and JWT signing certificates.

Note:

You can also define SAML and JWT trusted issuers using WLST, as described in "Defining Trusted Issuers and Managing DN Lists Using WLST".

The list of trusted issuers that you define here becomes the default list that is applicable to all applications in the instance. When you add an issuer using this method, it does not require a server restart.

By default, MSAS checks the incoming issuer name against the list of configured issuers, and checks the SAML and JWT signatures against the configured certificates in the MSAS keystore. If you defined a trusted DNs list for a trusted issuer, MSAS also verifies that the SAML and JWT signatures are signed by a certificate whose DN belongs to the trusted DN list.

Configuration of the trusted DNs list is optional; it is available for users that require more fine-grained control to associate each issuer with a list of one or more signing certificates. If you do not define a list of DNs for a trusted issuer, then MSAS allows signing by any certificate, as long as all the intermediate certificates and the CA certificate in the certificate chain for the signing certificate are present in the MSAS keystore. If the signing certificate is self-signed, it must be in the keystore itself.

Important Notes:

  • Using the SAML and JWT Trust tables on the Authentication tab, you define the DNs of the signing certificates, not the certificates themselves.

  • The CA and intermediate certificates for the signing certificate must be in the MSAS keystore regardless of whether the signing certificate is in the keystore or passed in the message.

  • For two-way SSL:

    • The certificate needs to be imported into the trust store for the Java EE container.

    • The DN of the client SSL certificates are used for validation and must be present in the trusted DNs list.

  • In all cases, the signing certificates must be trusted by the certificates present in the MSAS keystore.

Use the following procedure to add SAML or JWT issuers, define a trusted DN list for SAML or JWT signing certificates, or to add a DN to the DN list for an issuer:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. In the MSAS Instance Configuration page, select the Authentication tab.

  3. In the SAML Trust or JWT Trust section of the page, shown in Figure 6-2, do one of the following:

    • To add a SAML trusted issuer and define a trusted DN list for trusted STS servers, click Add in the Trusted STS table. Use this list for SAML HOK and SAML bearer.

    • To add a trusted issuer and define a trusted DN list for trusted SAML clients, click Add in the Trusted Clients table. Use this list for SAML sender vouches.

    • To add a trusted issuer and define a trusted DN list for trusted JWT issuers, click Add in the Trusted Issuer table.

  4. In the Issuer Name column, enter a trusted issuer, for example www.yourcompany.com. The default value for the predefined SAML and JWT client policies is www.oracle.com.

  5. In the Issuer DN column, enter the DN list for the trusted issuer. Use a string that conforms to RFC 2253. For example, the trusted DN for the trusted issuer www.oracle.com is CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US. To add more than one DN for an issuer, separate each DN with a semicolon (;).

    For more information about RFC 2253, see http://www.ietf.org/rfc/rfc2253.txt.

    Figure 6-2 SAML and JWT Trust Section of Authentication Tab

    Description of Figure 6-2 follows
    Description of "Figure 6-2 SAML and JWT Trust Section of Authentication Tab"

  6. Optionally, add additional trusted issuers and DN lists. To do so, repeat steps 3 through 6.

  7. To add a DN to the DN list for a trusted issuer, select the trusted issuer in the table and append the DN to the list of DNs in the Issuer DN column. Be sure to separate each DN by a semicolon (;).

  8. To delete a trusted issuer, DN list, or individual DN from the list:

    • To delete a trusted issuer and the DN list, select the row containing the issuer to be deleted and click Delete.

    • To delete a DN list, clear the Issuer DN field for the DN to be deleted. Note that any configured token rules are also deleted.

    • To delete a DN from the DN list, select the row for the trusted issuer and delete the DN from the list.

    Note:

    The Configure Token Rule feature is reserved for future use.

  9. When you have finished configuring the necessary issuers and DN lists, click Apply.

  10. Optionally, if you want these changes to go into effect immediately, you can use the synchronize feature as described in "Synchronizing MSAS Instance Configuration".

6.2.4 Configuring Message Security

The Message Security tab of the MSAS Instance Configuration page enables you to specify signature and encryption aliases for the MSAS keystore, and to configure message security settings such as clock skew and message expiration time. This configuration is described in the following sections:

Note:

You can also configure message security using WLST, as described in "Configuring Message Security Using WLST".

6.2.4.1 Configuring the MSAS Keystore

When you create an MSAS instance using either the MSAS console or the configMSAS script, the MSAS signature keystore is created by default, using the MSAS instance name as the stripe name, such as kss://myinstance/keystore. The signing certificate of the MSM server using the alias msm_sign_cert0 is automatically imported into the keystore. If the signing certificate for the MSM is a certificate chain, the additional certificates are imported as well, for example msm_sign_cert1, msm_sign_cert2, and so on.

When you configure the identity store for the instance, it imports the default signature and encryption keys using the alias msas_id_orakey. Because this KSS keystore is defined at the instance level, the signature and encryption keys apply to all applications in the instance.

Note:

The MSAS keystore is not used for the SSL keys. For details about the SSL keystore and truststore, see Chapter 7, "Configuring the SSL Keystore and Truststore."

You can use the fields in the Keystore section to generate a keypair and import keys into the keystore, and to delete keys from the keystore. To do so:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. In the MSAS Instance Configuration page, click the Message Security tab.

  3. Click the Sign Alias alias key to import a new private signature key, or to generate a keypair.

    If you are configuring a logical instance that has not yet been bound to a physical instance, click Click to Add.

  4. To import a signature key and alias from a keystore, click Import From Keystore.

  5. Click Choose File to select the key file to be imported from the file system, and enter the alias of the key to be imported in the Alias field. If the keystore from which the key is being imported is password protected, complete the Keystore Password and Alias Password fields.

  6. Click Import.

    The key is added to the list of keys in the table.

  7. To generate a new keypair, click Generate Keypair, provide an alias and a distinguished name for the keypair as shown in Figure 6-3.

    Field Description
    Alias Enter an alias for the keypair. This field is required.
    Distinguished Name Specify the distinguished name (DN) of the certificate wrapping the keypair. This field is required.
    Algorithm Symmetric key algorithm. The default is RSA.
    Keysize The RSA keysize. The default is 1024 bytes.

    Figure 6-3 Generate Keypair Options in Private Key for Signing Window

    Description of Figure 6-3 follows
    Description of "Figure 6-3 Generate Keypair Options in Private Key for Signing Window"

  8. Click Generate Keypair.

    The keypair is added to the table.

  9. Select the key in the table to be used as the signature key and click OK.

  10. To import a new private key used for decrypting messages, or to generate an encryption keypair, click the Encrypt Alias alias key, then repeat steps 4 through 8 as required.

  11. Select the alias in the table to be used as the decryption key for the instance and click OK.

  12. To delete a signature or encryption key from list of available keys, click the Sign Alias or Encrypt Alias key and in the pop-up window, select the key to be deleted and click X, click Yes when prompted, then click OK.

    The entry is deleted from the table.

  13. Click Apply.

6.2.4.2 Configuring Security Settings

The Security Settings section of the Message Security tab allows you to tune security settings such as the default message timestamp skews between system clocks, and the message expiration time.

To configure the security settings:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the Message Security tab.

  3. In the Security Settings section of the page, set the following properties as required for your environment, then click Apply:

    • Clock Skew – Specify the tolerance of time differences, in milliseconds, between client and server machines. For example, when timestamps are sent in a message to a service that follows a different time zone, this property allows for the specified time tolerance. The default value is 360,000 milliseconds (6 minutes). To adjust the clock skew, enter a new value in the field or click the up/down arrows to increase or decrease the default value.

      You should configure this property as follows:

      • Increase the clock skew when the client and service are running on different systems and their system clocks are not in sync, which could result in the service rejecting messages from the client, with an error indicating the timestamp validation failed. Increasing the clock skew accounts for the difference in clocks between the client and the web service. For example, if the difference between the service clock and the client clock is 10 minutes, increase the Clock Skew on the system hosting the service to 10 minutes (600000 milliseconds).

      • Decrease the clock skew if you want to narrow the window in which the service is willing to accept messages from clients to avoid replay attacks.

    • Client Clock Skew—Tolerance of time, in seconds, that is used to calculate the NotBefore and NotOnOrAfter conditions for SAML and JWT token generation. Together, these conditions define the lower and upper boundaries to limit the validity of the token.

    • Message Expiration Time— Specify the duration of time, in seconds, before a message expires after its creation. This property is used in cases where a timestamp is sent across in the token to verify if the timestamp has expired or not. It is also used to control the timestamp expiry window on the client side when the message is created. The value specified here applies to all message protection and SAML and JWT assertion timestamp elements. The default value is 300,000 milliseconds (5 minutes).

      If the message expires when received by the service even when there is no time difference between the client's and service's clocks, then the message expiration time must be increased. The message expiration time is derived from the values of Message Expiration Time and the expiry time in the incoming message, and is the lesser of the two.

      For example, if the server's Message Expiration Time is set to 5 minutes and the incoming message expiry time is 6 minutes, then the effective timestamp validation window is only 5 minutes and the incoming message is only be valid in that 5 minute window. In this case, you need to increase the Message Expiration Time at the service side. (Increasing the timestamp expiry on the incoming message will not fix the problem because the message expiration time is derived from both values and is the lesser of the two.)

      On the other hand, if the server's Message Expiration Time is 5 minutes and the incoming message expiry time is 3 minutes, then the expiry time in the incoming message (that is, at the client side) must be increased.

      Note:

      A higher value of the Message Expiration Time may lead to a security vulnerability.

6.2.5 Configuring the Cache Refresh Time

The Policy Access tab of the MSAS Instance Configuration page enables you to configure the amount of time to wait between cache refreshes of the MSAS run-time cache. The physical MSAS instance fetches the configuration for the logical MSAS instance maintained in the MSAS repository and caches it. This cache is refreshed periodically based upon the setting defined in this section.

Note:

You can also configure the cache refresh time using WLST, as described in "Configuring the Cache Refresh Time Using WLST".

To configure the cache refresh time:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the Policy Access tab.

  3. In the Cache Management section of the page, configure the Cache Refresh Time property, which is the number of milliseconds to wait between cache refreshes. To set this property, enter a new value in the field, or click the up/down arrows to increase or decrease the default value. The default is 86,400,000 milliseconds (24 hours).

    Note:

    The remaining fields on this tab are reserved for future use.

  4. Click Apply to save the property updates.

6.2.6 Configuring Authentication Endpoints

The Authentication Endpoints tab of the MSAS Instance Configuration page enables you to configure the endpoints used for initial authentication of the user for each of the initial authentication types: KINIT, PKINIT, OAuth2, and Oracle Access Manager Mobile and Social.

Note:

You can also configure the authentication endpoints using WLST, as described in "Configuring the Authentication Endpoints Using WLST".

For initial authentication and generation of the session token, Mobile Security Access Server provides a virtual (reverse proxy) application that contains a URL for each of the initial authentication types. Each of these URLs is provisioned with a predefined policy for authentication on-request, and a session token (SToken) generation policy on response.

This topic contains the following sections:

6.2.6.1 Configuring KINIT and PKINIT Authentication

The KINIT & PKINIT section of the Authentication Endpoints tab enables you to configure the properties in the Kerberos configuration file krb5.conf that are required for Kerberos Password Authentication (KINIT) and Public Key Cryptography for Initial Authentication (PKINIT) to work.

The fields in this section allow you to add, edit, and delete Kerberos realms, add and delete DNS domains, specify Kerberos encryption types, specify the logging location for the Kerberos and KCM messages, and enable the use of PKINIT trust anchors. Note that manual changes to this krb5.conf file are not persisted because it is overwritten each time MSAS is restarted.

For more advanced configuration, you should create a krb5.conf manually and save it to instance_root/instance_name/config/default directory. Once you do so, it takes precedence over the krb5.conf file that is created using the console. You can then customize it, for example, to point to specific domain controllers or to accommodate environments with alternate UPN suffixes. For more information, see "Advanced Kerberos Configuration."

To configure KINIT and PKINIT:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the Authentication Endpoints tab.

  3. Expand the KINIT & PKINIT section (if it is not already expanded). The section is shown in Figure 6-4.

    Figure 6-4 KINIT & PKINIT Section on Authentication Endpoints Tab

    Description of Figure 6-4 follows
    Description of "Figure 6-4 KINIT & PKINIT Section on Authentication Endpoints Tab"

  4. In the Realms section, configure the Kerberos realm.

    1. Click Add to add a new Kerberos realm.

    2. In the Realm window, provide a name, KDC host and port, and a default domain for the realm, then click OK.

      Field Description
      Name Enter a name for the realm. The realm name must match the REALM name defined during the Active Directory setup.
      KDC host Enter the host for the KDC server running the realm specified in the Name field.
      KDC port Optionally, enter the port of the KDC server running the realm specified in the Name field.
      Default Domain Enter the name of the default domain in the field, or select a default domain from the menu.

      Typically, the domain name is in lower case, for example example.com.

      Note that the domain name is automatically added to the Domains table.

    3. To set a default realm, select the realm in the Realms table and click Set As Default.

    4. To edit an existing realm, select the realm in the Realms table and click Edit. Note that you cannot change the name of a realm. In the Realm window, enter a new KDC host, port, or default domain, then click OK.

    5. To delete a realm, select the realm in the Realms table and click Remove.

  5. In the Domains section, configure the DNS domains.

    1. Click Add to add a DNS domain.

    2. In the Domain field, enter the name, then in the Realm field, select an associated realm from the menu.

    3. To delete a domain, select the domain in the Domains table and click Remove.

  6. In the Encryption section, select the TKT and TGS encryption types.

    1. From the default TKT enctypes menu, select the session key encryption type that the client should use when making an initial authentication request (AS-REQ).

    2. From the default TGS enctypes menu, select the session key encryption type that the client should use when requesting a service ticket from the TGS (TGS_REQ).

    For a list of the supported encryption types, refer to the MIT Kerberos Documentation, "Encryption types" at http://web.mit.edu/Kerberos/krb5-1.12/doc/admin/conf_files/kdc_conf.html#encryption-types.

  7. In the Logging section, specify the logging location for the Kerberos and Kerberos Cache Manager (KCM) messages.

    Select the log locations to use for the Kerberos configuration messages (krb5 menu, and the KCM messages (KCM menu). Select STDERR to log messages using the standard error stream. Select File to log messages to a file, and in the empty field, enter the log file location.

  8. To view or edit the policy configuration of the KINIT endpoint:

    1. Click Edit Policy to display the URL Policy Configuration page for the endpoint in a new tab named AuthnService.

      Two policies are attached by default:

      The HTTP Kerberos Password Authentication Service Policy is attached to the On-Request endpoint. This internal policy enables the Kerberos password authentication.

      The HTTP Session Token Issue Policy is attached to the On-Response endpoint. This policy issues a session token with the authenticated user ID to the client.

    2. Select the policy name, or click the Options menu icon Options menu icon then Edit, to view the policy details and configure policy overrides.

    3. Optionally, click the Overrides tab to configure property overrides.

      In the HTTP Kerberos Password Authentication Service Policy you can configure the keystore.sig.csf.key, which is the CSF key used for the signature key name and password.

      In the HTTP Session Token Issue Policy, you can configure the keystore.sig.csf.key and the keystore.enc.csf.key, which is the alias of the certificate to be used for encrypting the session token.

      If you want to use a different signature or encryption key than the one configured for the instance, you can do so using these configuration overrides. To add a signature or encryption CSF key to the keystore press Click to add, then click Generate Keypair to generate a keypair or Import from Keystore to import a key from a keystore. When you have added the desired key, select the key in the table and click OK.

      Note:

      To ensure proper authentication on this endpoint, you should not delete the default policy attachments, or attach additional policies.

    4. If you have made changes to the policy configuration, click Validate to validate the policy, then click Apply to save your changes. Close the AuthnService tab.

      If you have not made any changes to the endpoint configuration, you can close the tab to return to the MSAS Instance Configuration page.

  9. In the PKINIT Trust Anchors section, you can enable trust anchors for PKINIT authentication. PKINIT trust anchors are stored in the trust store. You can also view and edit the policy configuration of the PKINIT endpoint.

    1. Click Enable to enable the use of PKINIT anchors to trust the authority issuing the KDC certificate,

    2. If desired, import a certificate into the truststore. To do so, click Choose File to select a file from the file system, enter an alias for the certificate in the Alias field, and click Import. The certificate is added to the table.

    3. Select the trusted certificate from the table to be used as the PKINIT anchor. The certificate you select must be the first certificate in the certificate chain. MSAS will automatically fetch the complete chain using the selected certificate as the starting point.

    4. To view or edit the policy configuration of the PKINIT endpoint, click Edit Policy to display the URL Policy Configuration page for the endpoint in a new tab named AuthnService.

      Two policies are attached by default:

      The HTTP Kerberos PKI Authentication Service Policy is attached to the On-Request endpoint. This internal policy enables the Kerberos PKI authentication.

      The HTTP Session Token Issue Policy is attached to the On-Response endpoint. This policy issues a session token with the authenticated user ID to the client.

    5. Select the policy name, or click the Options menu icon Options menu icon then Edit, to view the policy details and configure policy overrides.

    6. Optionally, click the Overrides tab to configure property overrides.

      In the HTTP Kerberos PKI Authentication Service Policy you can configure the keystore.sig.csf.key, which is the CSF key used for the signature key name and password.

      In the HTTP Session Token Issue Policy, you can configure the keystore.sig.csf.key and the keystore.enc.csf.key, which is the alias of the certificate to be used for encrypting the session token.

      If you want to use a different signature or encryption key than the one configured for the instance, you can do so using these configuration overrides. To add a signature or encryption csf key to the keystore press Click to add, then click Generate Keypair to generate a keypair or Import from Keystore to import a key from a keystore. When you have added the desired key, select the key in the table and click OK.

      Note:

      To ensure proper authentication on this endpoint, you should not delete the default policy attachments, or attach additional policies.

    7. If you have made changes to the policy configuration, click Validate to validate the policy then click Apply to save your changes. Close the AuthnService tab.

      If you have not made any changes to the endpoint configuration, you can close the tab to return to the MSAS Instance Configuration page.

  10. Click Apply at the top of the MSAS Instance Configuration page to save your changes.

6.2.6.2 Configuring OAuth2 Confidential Client Authentication

In order for the Mobile Security Access Server to authenticate users against Oracle Access Manager and retrieve Oracle Access Manager and OAuth tokens for integrated single sign on, the Mobile Security Access Server must be registered as an OAuth Confidential Client with the Oracle Access Manager OAuth Service.

The OAuth2 Confidential Client section of the Authentication Endpoints tab enables you to configure the OAuth2 confidential client endpoint required, and to specify the client ID and secret in the Credential Store Framework (CSF).

To configure the OAuth2 confidential client endpoint:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the Authentication Endpoints tab.

  3. Expand the OAuth2 Confidential Client section (if it is not already expanded).

  4. If it is not already configured, in the Endpoint field add the host and port for the OAuth Service Profile Endpoint to the endpoint URL, for example http://myhost:port/ms_oauth/oauth2/endpoints/oauthservice. This is the endpoint to which the MSAS server creates JWT User Token and OAM Tokens for OAuth2 Confidential Client Authentication flow.

  5. Click Edit Policy to view the policy configuration for the endpoint and to specify the CSF client key. The URL Policy Configuration page for the endpoint opens in a new tab named AuthnService.

    Two policies are attached by default.

    The HTTP OAuth2 Confidential Client Over SSL Policy is attached to the On-Request policy enforcement endpoint. This internal policy performs OAuth2 confidential client authentication and creates OAuth and OAM tokens.

    The HTTP Session Token Issue Policy is attached to the On-Response policy enforcement endpoint. This policy issues a session token with the authenticated user ID to the client.

  6. Select the HTTP OAuth2 Confidential Client Over SSL Policy policy name, or click the Options menu icon Options menu icon then Edit, to view the policy details and configure policy overrides.

  7. Optionally, click the Overrides tab to configure the policy overrides.

    • In the HTTP OAuth2 Confidential Client Over SSL Policy, you can configure the oauth2.client.csf.key property. The default value of this property in the policy is set to oauth2.confidential.client.credentials. When you create the instance using configMSAS, it creates a CSF key for this property with a default client ID and password. The client ID is in the format MSAS_Instance_ID_MSASClient, for example myinstance1_MSASClient, and the password is randomly generated.

      To change this value, enter the OAuth2 client CSF key in the Value field then click Apply.

    • In the HTTP Session Token Issue Policy, you can configure the keystore.sig.csf.key and the keystore.enc.csf.key, which is the alias of the certificate to be used for encrypting the session token.

      If you want to use a different signature or encryption key than the one configured for the instance, you can do so using these configuration overrides. To add a signature or encryption csf key to the keystore press Click to add, then click Generate Keypair to generate a keypair or Import from Keystore to import a key from a keystore. When you have added the desired key, select the key in the table and click OK.

    Note:

    To ensure proper authentication on this endpoint, you should not delete the default policy attachments, or attach additional policies.

  8. If you have made changes to the policy configuration, click Validate to validate the policy then click Apply to save your changes. Close the AuthnService tab.

    If you have not made any changes to the endpoint configuration, you can close the tab to return to the MSAS Instance Configuration page.

  9. Click Apply at the top of the MSAS Instance Configuration page to save your changes.

6.2.6.3 Configuring Oracle Access Manager Mobile and Social (OAMMS) Authentication

The OAuth2 Mobile Client section of the Authentication Endpoints tab enables you to configure the OAuth2 mobile client endpoint required for Oracle Access Manager Mobile and Social mobile client authentication, and to specify the client ID and secret in the Credential Store Framework (CSF).

To configure the OAuth2 mobile client endpoint:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the Authentication Endpoints tab.

  3. Expand the OAuth2 Mobile Client section (if it is not already expanded).

  4. If it is not already configured, in the Endpoint field add the host and port for the OAuth Service Profile Endpoint to the endpoint URL, for example http://myhost:port/ms_oauth/oauth2/endpoints/oauthservice. This is the endpoint to which the MSAS server creates JWT User Token and OAM Tokens for OAuth2 Mobile Client Authentication flow.

  5. Click Edit Policy to view the policy configuration for the endpoint and to specify the CSF client key. The URL Policy Configuration page for the endpoint opens in a new tab named AuthnService.

    Two policies are attached by default.

    The HTTP OAuth2 Mobile Client Over SSL Policy is attached to the On-Request policy enforcement point. This internal policy performs OAuth2 mobile client authentication and creates OAuth and OAM tokens.

    The HTTP Session Token Issue Policy is attached to the On-Response policy enforcement point. This policy issues a session token with the authenticated user ID to the client.

  6. Select the HTTP OAuth2 Mobile Client Over SSL Policy policy name, or click the Options menu icon Options menu icon then Edit, to view the policy details and configure policy overrides.

  7. Optionally, click the Overrides tab to configure the policy overrides.

    • In the HTTP OAuth2 Mobile Client Over SSL Policy, you can configure the oauth2.mobile.client.csf.key property. The default value of this property in the policy is set to oauth2.mobile.client.id. When you create the instance using configMSAS, it creates a CSF key for this property with a default client ID and password. The client ID is in the format MSAS_Instance_ID_OracleContainer, for example myinstance1_OracleContainer. The password can be any value as it is not used in this configuration.

      To change this value, enter the OAuth2 client CSF key in the Value field then click Apply.

    • In the HTTP Session Token Issue Policy, you can configure the keystore.sig.csf.key and the keystore.enc.csf.key, which is the alias of the certificate to be used for encrypting the session token.

      If you want to use a different signature or encryption key than the one configured for the instance, you can do so using these configuration overrides. To add a signature or encryption csf key to the keystore press Click to add, then click Generate Keypair to generate a keypair or Import from Keystore to import a key from a keystore. When you have added the desired key, select the key in the table and click OK.

    Note:

    To ensure proper authentication on this endpoint, you should not delete the default policy attachments, or attach additional policies.

  8. If you have made changes to the policy configuration, click Validate to validate the policy then click Apply to save your changes. Close the AuthnService tab.

    If you have not made any changes to the endpoint configuration, you can close the tab to return to the MSAS Instance Configuration page.

  9. Click Apply at the top of the MSAS Instance Configuration page to save your changes.

6.2.6.4 Configuring the Crypto Service

The Crypto Service section of the Authentication Endpoints tab enables you to configure the key rollover feature in the PKI Crypto Service and to modify the policy endpoint configuration if desired.

To configure the Crypto service endpoint:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the Authentication Endpoints tab.

  3. Expand the Crypto Service section (if it is not already expanded).

  4. Optionally, you can enable the key rollover aliases feature. By default, the Key Rollover Aliases field is blank, and key rollover support is not enabled. To enable key rollover, select an alias from the menu, or select All. The aliases selected will be added to the ordered list of aliases used in the rollover feature. A decryption error will not be returned by the crypto service unless decryption of a given ciphertext fails with all archived private keys.

    Whenever you change the encryption/signing key of MSAS, be sure to add the new signing keys as a new entry and keep the existing keys in the keystore. The alias that you select here should be the older key alias. Be sure to do this every time that you add an encryption key to the keystore, always ensuring you are adding the older key to this list. Doing so ensures that data encrypted using older keys can still be decrypted even if you have changed the keys.

  5. Click Edit Policy to view the policy configuration for the endpoint. The URL Policy Configuration page for the endpoint opens in a new tab named AuthnService.

    Two policies are attached by default to the On-Request policy enforcement point.

    • The HTTP Session Token Verify Policy verifies the session token, including the timestamp and signature, decrypts the encrypted data, and asserts the identity using the user ID from the session token. The request is rejected if the verification fails.

    • The HTTP Action Security Policy performs SKEK encryption and decryption.

  6. Optionally, select the HTTP Session Token Verify Policy name or click the Options menu icon Options menu icon then Edit, to view the policy details and configure policy overrides.

    If you want to use a different signature or encryption key than the one configured for the instance, you can do so using these configuration overrides. You can configure the keystore.sig.csf.key, which is the CSF key used for the signature key name and password and the keystore.enc.csf.key, which is the alias of the certificate to be used for encrypting the session token.

    To add a signature or encryption csf key to the keystore, press Click to add, then click Generate Keypair to generate a keypair or Import from Keystore to import a key from a keystore. When you have added the desired key, select the key in the table and click OK.

    Note:

    To ensure proper authentication on this endpoint, you should not delete the default policy attachments, or attach additional policies.

  7. If you have made changes to the policy configuration, click Validate to validate the policy then click Apply to save your changes. Close the AuthnService tab.

    If you have not made any changes to the endpoint configuration, you can close the tab to return to the MSAS Instance Configuration page.

  8. Click Apply at the top of the MSAS Instance Configuration page to save your changes.

6.2.7 Configuring System Settings

The System Settings tab of the MSAS Instance Configuration page enables you to configure settings for outbound message, proxy servers, load balancing, SSL, and logging. This configuration is described in the following sections:

Notes:

For details on logging configuration, see Chapter 9, "Managing Log Files."

You can also configure system settings using WLST as described in "Configuring System Settings Using WLST".

6.2.7.1 Configure Outbound Message Settings

The Outbound Message Settings section on the System Settings tab enables you to configure the client connection to back-end services.

To configure the outbound message settings:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the System Settings tab.

  3. Expand the Outbound Message Settings section (if it is not already expanded).

  4. Specify the connection pool settings and connection timeouts. To do, click in the field to see the default, and adjust the value by clicking the up and down arrows.

    Field Description
    Total Connections in pool Specify the maximum number of connections in a pool that a client can handle. The default is 512.
    Maximum Connections per host Specify the maximum number of connections in a pool, per host, that a client can handle. The default is 25.
    Connection Timeout Specify the maximum time in milliseconds a client can wait when connecting to a back-end host. The default is 20,000 ms.
    Idle Connection pool Timeout Specify the maximum time in milliseconds a client will keep idle connections in the pool.The default is 180,000 ms (3 minutes).
    Request Timeout Specify the maximum time in milliseconds a client can wait for a response. The default is 60,000 ms (1 minute).

  5. Click Apply at the top of the page to save your changes.

  6. Restart the MSAS server.

6.2.7.2 Configure Proxy Server Settings

The Proxy Server Settings section on the System Settings tab enables you to configure the proxy server used for outbound calls to the internet through MSAS for back-end applications and services.

To configure the proxy server settings:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the System Settings tab.

  3. Expand the Proxy Server Settings section (if it is not already expanded).

  4. Specify the settings for the proxy server, including the host name and port, user ID and password, and the list of hosts that will not use the proxy.

    Field Description
    Name Enter a name for the proxy server to uniquely identify it. This field is optional.
    Host Name Enter the host name of the proxy server.
    Port Enter the port number of the proxy server.
    User Name Enter the user ID to connect to the proxy server.

    Note: The User Name and Password is required only if the proxy server requires authentication.
    Password Enter the password corresponding to the proxy server user ID.
    Hostnames without proxy Enter one or more hosts that will not use the proxy server. This field supports the asterisk * wildcard, but only as a prefix and suffix.

    By default, this field contains the value localhost, 127.0.0.1.

  5. Click Apply at the top of the page to save your changes.

  6. Restart the MSAS server.

6.2.7.3 Configure Server Settings

The Server Settings section on the System Settings tab enables you to configure general server settings for the MSAS server, such as load balancing URLs, and Service Principal Name and URL mapping.

To configure the server settings:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the System Settings tab.

  3. Expand the Server Settings section (if it is not already expanded).

  4. Specify the load balancer URLs for the server.

    Field Description
    Load Balancer URL Enter a non-SSL URL for a front ending load balancer, for example http://lbr.example.org:80.
    Load Balancer SSL URL Enter an SSL URL for a front-ending load balancer, for example https://lbr.example.org:443.

  5. In the Service Principal Name section, complete the fields to map a URL to a Service Principal Name. Service Principal Name is required for the NTLM and SPNEGO protocols.

    1. In the URL field, enter the Service Principal Name URL. You can use the * wildcard anywhere in the URL, for example http*://example.host*80/* or *.example.org.

    2. In the Service Principal Name field, enter the Service Principal Name in the form of SPN_SERVICECLASS/SPN_HOSTNAME.

    3. To add more Service Principal Names, click Add and, in the new row, enter the values in the URL and Service Principal Name field.

    4. To delete a Service Principal Name, select the row and click Remove.

  6. Click Apply at the top of the page to save your changes.

6.2.7.4 Configuring the SSL Keystore and Truststore

The SSL Settings section on the System Settings tab enables you to add certificates to the SSL Truststore and private keys to the SSL keystore. The SSL keystore is used for inbound SSL connections to MSAS and as the MSAS identity keystore. The SSL truststore serves as the repository for trusted certificates used for trusting or authenticating client certificates (for two-way SSL).

To configure the SSL settings:

  1. Navigate to the MSAS Instance Configuration page:

    1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

    2. In the Mobile Security Access Server section, click Environments.

      The MSAS Environments page opens in a new tab.

    3. Click MSAS or Instances in the MSAS tile.

      The MSAS Instances Summary page opens in a new tab.

    4. Click the instance name or Configure in the tile for the desired instance.

      The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  2. Select the System Settings tab.

  3. Expand the SSL Settings section (if it is not already expanded).

    The SSL TrustStore Location and SSL KeyStore Location fields are read-only, and contain the location of the SSL truststore and SSL keystore for the instance. Note that only KSS keystores are supported, therefore these fields must contain a KSS URI.

  4. To import a server certificate into the SSL trust store:

    1. Click Click To Import.

    2. In the Server Certificate window, click Choose File and select the certificate to be imported from the file system.

      Note:

      Only Base64-encoded certificates are supported.

    3. Enter an Alias for the certificate to be imported, select Trusted Certificate from the Certificate Type menu, and click Import.

      The imported certificate is added to the list of certificates in the table.

    4. Click Close to close the Server Certificate window.

  5. To import a private key or to generate a keypair to add to the SSL keystore:

    1. Click Click to add to display the Private Key window.

      From the Private Key window you can generate a keypair, or import a private key from a JKS keystore.

    2. To generate a private keypair for the MSAS SSL identity key., click Generate Keypair.

      In the Alias field, provide an alias for the keypair.

      In the Distinguished Name field, enter the distinguished name of the certificate wrapping the keypair.

      In the Algorithm field, enter a symmetric key algorithm. The default is RSA.

      In the Key Size field, enter the RSA key size. The default is 1024 bytes.

      Click Generate Keypair. The keypair is created and added to the keypair table.

    3. To import a Java keystore file into the keystore service, click Choose File and select the Java keystore file to be imported.

      If the JKS keystore from which the key file is being imported is password protected, enter the Keystore Password for the JKS keystore.

      Enter an Alias for the keypair, and, an Alias Password if the alias is password protected.

      Then click Import.

  6. Click Apply at the top of the page to save your changes.

  7. Restart the MSAS server.

6.3 Configuring an MSAS Instance Using WLST

You can use WLST commands to configure an MSAS instance, including identity store profiles, trusted issuers and DNs, message security, policy access, authentication endpoints, other security settings, and the MSAS heartbeat.

The majority of the properties used to configure an MSAS instance can be set using the setMSASConfiguration command. For details about using this command, see "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance".

Additional commands are provided to configure the identity store profile, trusted issuers and DN lists, the credential store, and the KSS keystore for MSAS. These commands are described in the relevant sections.

The following sections describe how to configure an MSAS instance using WLST commands.

6.3.1 Accessing the MSAS WLST Commands

The WLST commands used to configure MSAS instances must be executed from the ORACLE_IDM/common/bin directory of your Mobile Security Manager (MSM) installation. Before running these commands, ensure that the Administration Server for the MSM domain is running.

To access the MSAS WLST commands:

  1. Go to the ORACLE_IDM/common/bin directory of the Middleware home directory for your Mobile Security Manager installation, for example /home/oracle/omsm/ORACLE_IDM/common/bin.

  2. Start WLST in offline mode using the following command:

    ./wlst.sh

    To use the MSAS WLST commands, you must use WLST in online mode.

  3. Connect to the running Mobile Security Manager Administration Server using the connect() command.

    For example, the following command connects WLST to the Admin Server at the URL myAdminServer.example.com:7001 using the username/password credentials weblogic/password1:

    connect("weblogic","password1","t3://myAdminServer.example.com:7001")

6.3.2 Viewing MSAS Instance Configuration Using WLST

You can display all of the configuration properties, with their values and groups, as specified in the current configuration document in the repository. If a property is not defined in the configuration document, then the default value defined for the product is displayed.

To view the configuration for an MSAS instance:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Use the displayMSASConfiguration() command to display the MSAS instance configuration.

    displayMSASConfiguration([instanceName=None])

    For example, to display the configuration for the instance named myinstance1, enter the following command:

    wls:/new_domain/serverConfig> displayMSASConfiguration('myinstance1')
.
.
.
Name: "client.clock.skew" Category: "Agent" Source: "default"
Value: 0
 
Name: "compliance.check" Category: "Agent" Source: "default"
Value: true
 
Name: "clock.skew" Category: "Agent" Source: "default"
Value: 360000
 
Name: "expire.time" Category: "Agent" Source: "default"
Value: 300000
 
Name: "cache.refresh.repeat" Category: "BeanAccessor" Source: "default"
Value: 600000
.
.
.

Note that the output displayed above shows the source of the configuration property settings as default, indicating the setting is from the default configuration document for the product. If you have modified a setting, it is saved in a configuration document for your instance, and will be reflected in the SOURCE field. For example:

Name: "max.connection.pool.per.host" Category: "ClientConfiguration" Source: "myinstance1"
Value: 100

Note:

Some of the properties that are displayed in the output of the displayMSASConfiguration command are not supported in this release of Mobile Security Access Server and are reserved for future use. This applies specifically to the properties in the following categories:

  • ConfigManager

  • Identity

  • IssuedToken

  • ClassPathAccessor

6.3.3 Using the setMSASConfiguration WLST Command to Configure an MSAS Instance

Many of the instance-level configuration properties can be set using the setMSASConfiguration command, as described in this section. You do not need to use the setMSASConfiguration command in the context of a session.

To set or modify the configuration properties for the MSAS instance using the setMSASConfiguration command:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Optionally, use the displayWSMConfiguration() command to view the current configuration for the instance as described in "Viewing MSAS Instance Configuration Using WLST".

  3. Use the setMSASConfiguration() command to set the desired configuration properties.

    setMSASConfiguration (instanceName,categoryName,propertyName,[groupName=None],[PropertyValues=None])

    In this command:

    • instanceName—The MSAS instance for which the configuration is to be modified.

    • categoryName—The category to which the property belongs. The category is verified against the default set of properties to ensure it is valid. This field is required.

    • propertyName—The name of the property. The name is verified against the default set of properties to ensure it is valid. This field is required.

    • groupName—The group containing the set of values to add in the configuration document. If the group exists, and this value is set to None, the group is removed. This field is optional.

    • propertyValues—The array of values to set for a property or group in the configuration document. The default is None, which refers to an empty array list. This field is optional.

    This command behaves as follows:

    • If a property is already defined, you can update it by entering the updated value in the propertyValues field. The property is set to the new value.

    • To clear a property setting, do not enter a value in the propertyValues field.

    For example, to modify the maximum connection pool properties for outbound message settings:

    wls:/base_domain/serverConfig> setMSASConfiguration('myinstance1','ClientConfiguration','max.connection.pool.total',None,['1000'])
 
A new property "max.connection.pool.total" within category "ClientConfiguration" has been added.
The values "[1000]" have been added to property "max.connection.pool.total" within category "ClientConfiguration".
Configuration properties associated with the MSAS instance "myinstance1" has been updated.
 
wls:/base_domain/serverConfig> setMSASConfiguration('myinstance1','ClientConfiguration','max.connection.pool.per.host',None,['100'])
 
A new property "max.connection.pool.per.host" within category "ClientConfiguration" has been added.
The values "[100]" have been added to property "max.connection.pool.per.host" within category "ClientConfiguration".
Configuration properties associated with the MSAS instance "myinstance1" has been updated.

    For example, to clear the maximum connections per host property:

    wls:/base_domain/serverConfig> setMSASConfiguration('myinstance1','ClientConfiguration','max.connection.pool.per.host',None,None)
 
Value elements removed from the property "max.connection.pool.total" within category "ClientConfiguration".
The property "max.connection.pool.total" within category "ClientConfiguration" has been removed.
Configuration properties associated with the MSAS instance "myinstance1" has been updated.

    Note:

    If you do not modify a configuration property, or you remove a property as shown in the example above, the default value is used at run time.

    Refer to the subsequent sections for the list of configuration properties and the default values for each type of configuration.

6.3.4 Configuring an Identity Store Profile Using WLST

Mobile Security Access Server includes WLST commands that provide the ability to add an identity store profile to the MSAS instance, edit an existing profile, delete a profile, and set the default profile.

An identity store profile is a logical representation of a user repository. All user and group entities are present in this identity store. There can be multiple profiles associated with an MSAS instance, and one profile can be marked as the default against which all authentication and user profile queries will occur.

The identity store configuration is stored in an Identity Profile Document in the MSAS Repository.

When using WLST to create, modify, and delete identity store profile documents, you must execute the commands in the context of a session. Each session applies to a single identity store profile document only.

For more information about these commands, see "MSAS Identity Store Profile Commands" in WebLogic Scripting Tool Command Reference for Identity and Access Management.

The following sections describe how to use WLST in interactive mode for identity profile management:

6.3.4.1 Creating an Identity Store Profile Using WLST

To create an identity store profile using WLST:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Start a repository session using the beginRepositorySession command.

    The beginRepositorySession command is used to create a session in which the repository will be modified. All creation, modification, or deletion commands must be performed in the context of a session. A session can only act on a single document.

    For example:

    wls:/base_domain/serverConfig> beginRepositorySession()

Repository Session begun.

  3. List the identity profile documents configured in an instance using the displayIdentityProfile command.

    displayIdentityProfile(instanceName, [profileName=None])

    In this command:

    • instanceName—The name of the MSAS instance for which you want to display the identity profiles. This field is required.

    • profileName—Name of a specific identity profile to be displayed. This field is optional. If no value is provided for the profileName argument, then all the identity profiles associated with the instance are displayed.

    For example:

    wls:/base_domain/serverConfig> displayIdentityProfile('myinstance1')
 
No identity profiles exist for instance "myinstance1"

  4. Use the createIdentityProfile command to create an identity store profile document.

    createIdentityProfile(instanceName, profileName, [description=None])

    In this command:

    • instanceName—The name of the MSAS instance for which you want to create an identity profile. This field is required.

    • profileName—Name for the identity profile.

    • description—Description of the identity profile. This argument is optional.

    For example:

    wls:/base_domain/serverConfig> createIdentityProfile('myinstance1','identity-profile1','Identity Profile 1')
Identity profile "identity-profile1" for instance "myinstance1" is successfully created in session.
Commit session will be required to reflect the operation in the repository.

    Notes:

    You cannot create multiple identity profiles within a session. You must commit the session, and then start a new session to create another identity profile.

  5. To set the identity profile directory, use the setIdentityProfileDirectory command.

    setIdentityProfileDirectory(directoryType, hostport, bindDN, bindPass, baseDN, isSecure)

    In this command:

    • directoryType—Type of directory to use for the identity profile. Supported values are:

      • OID (Oracle Internet Directory)

      • OUD (Oracle Unified Directory)

      • ACTIVE_DIRECTORY

      • ODSEE (Oracle Directory Server Enterprise Edition)

      • WLS_LDAP (Embedded LDAP in WebLogic Server)

    • hostport—Host name and port of the server running the selected directory.

    • bindDN—DistinguishedName (DN) of the user to connect to the directory.

    • bindPass—Password for the Bind DN to connect to the directory.

    • baseDN—LDAP Searchbase under which all users and groups are located in the LDAP directory. For example, cn=us, dn=mycompany, dc=com.

    • isSecure—Flag (boolean) to indicate if the connection to the directory should be made over SSL. When set to true, the connection is configured over SSL.

    For example:

    wls:/base_domain/serverConfig> setIdentityProfileDirectory('OID',['host1.mycompany.com:5678'],'cn=host,dn=mycompany,dn=com','welcome','cn=us,dn=mycompany,dn=com',false)
 
Directory information for identity profile set successfully.

  6. To set the user information for an identity profile, use the setIdentityProfileUser command.

    setIdentityProfileUser(baseDN, loginIDAttribute, objectClassNames)

    In this command:

    • baseDN—Base DNs used to create or search for users. For example, cn=users, dn=mycompany, dc=com.

    • loginIDAttribute—Login ID for the user. Typically, this is the uid or mail attribute in the LDAP. In Active Directory, this refers to the UserPrincipalName.

    • objectClassNames—Fully qualified names of the schema classes used to represent users. Typically, this field is set to the standard LDAP objectclass inetorgperson.

    For example:

    wls:/base_domain/serverConfig> setIdentityProfileUser('cn=users,dc=mycompany,dc=com','uid',['inetorgperson'])
 
User information for identity profile set successfully.

  7. To set the group information for an identity profile, use the setIdentityProfileGroup command.

    setIdentityProfileGroup(baseDN, groupNameAttribute, objectClassNames)

    In this command:

    • baseDN—Base DNs used to create groups or enterprise roles. For example, cn=group, dn=mycompany, dc=com.

    • groupNameAttribute—Attribute that uniquely identifies the name of the enterprise group or role.

    • objectClassNames—List of objectclasses used to identify the enterprise roles or groups. Typically, this field is set to the standard LDAP standard objectclass groupofuniquenames. In Active Directory, this is group.

    For example:

    wls:/base_domain/serverConfig> setIdentityProfileGroup('cn=group,dc=mycompany,dc=com','cn',['groupofuniquenames'])
 
Group information for identity profile set successfully.

  8. Write the current contents of the session to the MSAS Repository using the commitRepositorySession command.

    For example:

    wls:/base_domain/serverConfig> commitRepositorySession()
 
create operation performed successfully on identity profile "identity-profile1" for instance "myinstance1".

    Alternatively, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

  9. To set an identity profile as the default, use the setMSASConfiguration command.

    Note:

    This step must be performed before you can use this identity profile at run time. For details about using this command, see "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance".

    For example:

    wls:/base_domain/serverConfig> setMSASConfiguration('myinstance1','IdentityProfile','name',None,['identity-profile1'])
 
The values "[identity-profile1]" have been added to property "name" within category "IdentityProfile".
Configuration properties associated with the MSAS instance "myinstance1" has been updated.

  10. To use this new identity store profile, you must restart the MSAS server.

6.3.4.2 Updating an Identity Profile Using WLST

To update an identity store profile using WLST:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Start a repository session using the beginRepositorySession command.

    The beginRepositorySession command is used to create a session in which the repository will be modified. All creation, modification, or deletion commands must be performed in the context of a session. A session can only act on a single document.

    For example:

    wls:/base_domain/serverConfig> beginRepositorySession()

Repository Session begun.

  3. List the identity profile documents configured in an instance using the displayIdentityProfile command.

    displayIdentityProfile(instanceName, [profileName=None])

    In this command:

    • instanceName—The name of the MSAS instance for which you want to display the identity profiles. This field is required.

    • profileName—Name of a specific identity profile to be displayed. This field is optional. If no value is provided for the profileName argument, then all the identity profiles associated with the instance are displayed.

    For example:

    wls:/base_domain/serverConfig> displayIdentityProfile('myinstance1')
 
Identity Profiles for instance "myinstance1":identity-profile1

  4. To display the contents of the identity profile, use the displayIdentityProfile command with the profileName argument.

    For example:

    wls:/base_domain/serverConfig> displayIdentityProfile('myinstance1','identity-profile1')

Name : identity-profile1
Instance name : myinstance1
Description : Identity Profile 1

Directory Information:
        Directory Type : OID
        Bind DN : cn=host,dn=mycompany,dn=com
        Base DN : cn=us,dn=mycompany,dn=com
        Hosts : host1.mycompany.com:5335
        SSL Enabled :  false


User Information:
        Base DN : cn=users,dc=mycompany,dc=com
        Login ID Attribute : uid
        Object class names : inetorgperson


Group Information:
        Base DN : cn=group,dc=mycompany,dc=com
        Group Name Attribute : cn
        Object class names : groupofuniquenames


Commit session will be required to reflect the operation in the repository.

  5. Select the identity profile to be updated using the selectIdentityProfile command.

    selectIdentityProfile(instanceName, profileName)

    In this command:

    • instanceName—The name of the MSAS instance for which you want to edit the identity profile. This field is required.

    • profileName—Name for the identity profile to be edited.

    For example:

    wls:/base_domain/serverConfig> selectIdentityProfile('myinstance1','identity-profile')
 

Identity profile "identity-profile1" for instance "myinstance1" selected for modification.

  6. To edit the profile directory, for example, use the setIdentityProfileDirectory command.

    setIdentityProfileDirectory(directoryType, hostport, bindDN, bindPass, baseDN, isSecure)

    In this command:

    • directoryType—Type of directory to use for the identity profile. Supported values are:

      • OID (Oracle Internet Directory)

      • OUD (Oracle Unified Directory)

      • ACTIVE_DIRECTORY

      • ODSEE (Oracle Directory Server Enterprise Edition)

      • WLS_LDAP (Embedded LDAP in WebLogic Server)

    • hostport—Host name and port of the server running the selected directory.

    • bindDN—DistinguishedName (DN) of the user to connect to the directory.

    • bindPass—Password for the Bind DN to connect to the directory.

    • baseDN—LDAP Searchbase under which all users and groups are located in the LDAP directory. For example, cn=us, dn=mycompany, dc=com.

    • isSecure—Flag (boolean) to indicate if the connection to the directory should be made over SSL. When set to true, the connection is configured over SSL.

    For example, to change the directory type from OID to WLS_LDAP:

    wls:/base_domain/serverConfig> setIdentityProfileDirectory('WLS_LDAP',['host1.mycompany.com:5678'],'cn=host,dn=mycompany,dn=com','welcome','cn=us,dn=mycompany,dn=com',false)
 
Directory information for identity profile set successfully.

  7. Optionally, display the contents of the identity profile again, using the displayIdentityProfile command with the profileName argument.

    Note:

    When you execute this command within a session, the session changes are displayed. If you execute it outside of a session, the contents of the repository are displayed.

    For example:

    wls:/base_domain/serverConfig> displayIdentityProfile('myinstance1','identity-profile1')
Identity profile "identity-profile1" for instance "myinstance1" is selected for update operation in session.

Name : identity-profile1
Instance name : myinstance1
Description : Identity Profile 1


Directory Information:
        Directory Type : WLS_LDAP
        Bind DN : cn=host,dn=mycompany,dn=com
        Base DN : cn=us,dn=mycompany,dn=com
        Hosts : host1.mycompany.com:5678
        SSL Enabled :  false

User Information:
        Base DN : cn=users,dc=mycompany,dc=com
        Login ID Attribute : uid
        Object class names : inetorgperson


Group Information:
        Base DN : cn=group,dc=mycompany,dc=com
        Group Name Attribute : cn
        Object class names : groupofuniquenames

  8. Write the current contents of the session to the MSAS Repository using the commitRepositorySession command.

    For example:

    wls:/base_domain/serverConfig> commitRepositorySession()
 
update operation performed successfully on identity profile "identity-profile1" for instance "myinstance1".

  9. Optionally, use the setMSASConfiguration command to set the updated identity profile as the default. This step is only required if you want to use the updated identity profile as the default and it was not previously set as the default profile.

    For example:

    wls:/base_domain/serverConfig> setMSASConfiguration('myinstance1','IdentityProfile','name',None,['identity-profile1'])
 
The values "[identity-profile1]" have been added to property "name" within category "IdentityProfile".
Configuration properties associated with the MSAS instance "myinstance1" has been updated.

  10. Restart the MSAS server.

6.3.4.3 Deleting an Identity Profile

To delete an identity profile using WLST:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Start a repository session using the beginRepositorySession command.

    The beginRepositorySession command is used to create a session in which the repository will be modified. All creation, modification, or deletion commands must be performed in the context of a session. A session can only act on a single document.

    For example:

    wls:/base_domain/serverConfig> beginRepositorySession()

Repository Session begun.

  3. Optionally, list the identity profile documents configured in an instance using the displayIdentityProfile command.

    displayIdentityProfile(instanceName, [profileName=None])

    In this command:

    • instanceName—The name of the MSAS instance for which you want to display the identity profiles. This field is required.

    • profileName—Name of a specific identity profile to be displayed. This field is optional. If no value is provided for the profileName argument, then all the identity profiles associated with the instance are displayed.

    For example:

    wls:/base_domain/serverConfig> displayIdentityProfile('myinstance1')
 
Identity Profiles for instance "myinstance1":identity-profile1

  4. Delete the identity profile using the deleteIdentityProfile command.

    deleteIdentityProfile(instanceName, profileName)

    In this command:

    • instanceName—The name of the MSAS instance associated with the identity profile. This field is required.

    • profileName—Name of the identity profile to be deleted.

    For example:

    wls:/base_domain/serverConfig> deleteIdentityProfile('myinstance1','identity-profile1')
 
Identity profile "identity-profile1" for instance "myinstance1" is successfully deleted in session.
Commit session will be required to reflect the operation in the repository.

  5. Write the current contents of the session to the MSAS Repository using the commitRepositorySession command.

    For example:

    wls:/base_domain/serverConfig> commitRepositorySession()
 
delete operation performed successfully on identity profile "identity-profile1" for instance "myinstance1".

  6. If the identity profile that you deleted was set as the default profile for the instance, you need to run the setMSASConfiguration command to either clear the property if a different profile is not available, or set a different profile as the default profile.

    For example, to clear the property, enter:

    wls:/base_domain/serverConfig> setMSASConfiguration('myinstance1','IdentityProfile','name',None, None)

Value elements removed from the property "name" within category "IdentityProfile".
The property "name" within category "IdentityProfile" has been removed.
Configuration properties associated with the MSAS instance "myinstance1" has been updated.

    To set a different profile as the default, enter:

    wls:/base_domain/serverConfig> setMSASConfiguration('myinstance1','IdentityProfile','name',None,['identity-profile2'])
 
The values "[identity-profile2]" have been added to property "name" within category "IdentityProfile".
Configuration properties associated with the MSAS instance "myinstance1" has been updated.

  7. Restart the MSAS server.

6.3.5 Defining Trusted Issuers and Managing DN Lists Using WLST

SAML and JWT trusted issuers and DN lists are stored in trust configuration documents in the MSAS repository. To configure trusted issuers and DN lists, you must create a new document or edit an existing document in the repository.

When using WLST to create, modify, and delete token issuer trust documents, you must execute the commands in the context of a session. Each session applies to a single trust document only.

For more information about trusted issuers and DN lists, see "Configuring Trusted Issuers and DN Lists for Signing Certificates".

The following sections describe how to use WLST commands in interactive mode to define trusted issuers and DN lists, how to import and export trust metadata, and how to revoke trust from a trusted issuer.

6.3.5.1 Configuring Trusted Issuers and DN Lists Using WLST

To configure SAML and JWT trusted issuers and DN lists using WLST:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Start a repository session using the beginRepositorySession command.

    The beginRepositorySession command is used to create a session in which the repository will be modified. All creation, modification, or deletion commands must be performed in the context of a session. A session can only act on a single document.

    For example:

    wls:/base_domain/serverConfig> beginRepositorySession()

Repository session begun.

  3. List the token issuer trust documents in the repository using the listWSMTokenIssuerTrustDocuments command.

    listWSMTokenIssuerTrustDocuments(name=None, detail='false')

    When used without any arguments, all the token issuer trust documents in the repository are listed. If you set the detail argument to true, the display name and the status of the document are also displayed. You can use the wildcard character * anywhere in the name argument. If no wildcard is specified, then the exact value entered for the name argument is used as the document name.

    For example:

    wls:/base_domain/serverConfig> listWSMTokenIssuerTrustDocuments('true')
 
Starting Operation listWSMTokenIssuerTrustDocuments ...
 
There are no token issuer trust documents in the repository.

  4. Do one of the following:

    • If a token issuer trust domain document does not exist for your domain, create one using the createWSMTokenIssuerTrustDocument command. The name argument is required.

      Note:

      Once you execute this command, you must run the setMSASConfiguration command using the properties specified in the output of the createWSMTokenIssuerTrustDocument command.
      createWSMTokenIssuerTrustDocument(name, displayName)

      For example:

      wls:/base_domain/serverConfig> createWSMTokenIssuerTrustDocument('trust_t1')
 
New Token Issuer Trust document named "trust_t1" created.
To use the new document in the domain configuration, you must run the setConfiguration command where category = "TokenIssuerTrust", property name = "name" and value = "trust_t1".

wls:/base_domain/serverConfig> setMSASConfiguration ('myinstance1','TokenIssuerTrust','name',None,['trust_t1'])

The values "[trust_t1]" have been added to property "name" within category "TokenIssuerTrust".
Configuration properties associated with the MSAS instance "myinstance1" has been updated.

    • If the token issuer trust document already exists for your domain, select the document for modification using the selectWSMTokenIssuerTrustDocument command. The name argument is required.

      selectWSMTokenIssuerTrustDocument(name)

      For example:

      wls:/base_domain/serverConfig> selectWSMTokenIssuerTrustDocument('trust_t1')
 
Token Issuer Trust document named "trust_t1" selected in the session.

  5. Optionally, specify a display name for the document using the setWSMTokenIssuerTrustDisplayName command. The display name is optional but can be useful for describing the documents. Note that if you specified a display name for the document when you created it, you can use this command to change the display name if desired.

    setWSMTokenIssuerTrustDisplayName(displayName)

    For example:

    wls:/base_domain/serverConfig> setWSMTokenIssuerTrustDisplayName('myinstance1 Trust Document')
 
Starting Operation setWSMTokenIssuerTrustDisplayName ...
 
Display Name of the document changed from null to myinstance1 Trust Document.

  6. Add the trusted issuers and define trusted keys or a trusted DN list using the setWSMTokenIssuerTrust command.

    setWSMTokenIssuerTrust(type, issuer, [trustedKeyIds=None])

    In this command:

    • type—The types of the tokens issued by the issuer and how the issuer signing certificates are identified with trustedKeyIds. Supported type values are shown in the following table.

      Use this type value... For this token type... With this key type... And this key identifier type
      dns.sv SAML SV X509 certificate DN
      dns.hok SAML HOK or Bearer X509 certificate DN
      dns.jwt JWT X509 certificate DN

    • issuer—Name of the trusted issuer, such as www.oracle.com.

    • trustedKeyIds—Optional argument used to specify the trusted key identifiers or the DN list for the issuer.

    This command behaves as follows:

    • If the trusted issuer already exists for the type specified, and you provide a list of DNs or aliases for the trustedKeyIds argument, the previous list is replaced with the new list. If you enter an empty set ([]) for the trustedKeyIds argument, then the list of DN values are deleted for the issuer.

    • If the trusted issuer does not exist for the type specified and you specify a value for the trustedKeyIds argument, the issuer is created with the associated DN list. If you do not set the trustedKeyIds argument, a new issuer is created with an empty DN list.

    In the following example, www.yourcompany.com is set as a trusted issuer. A DN list is not specified:

    wls:/base_domain/serverConfig> setWSMTokenIssuerTrust("dns.jwt","www.yourcompany.com",[])
 
Starting Operation setWSMTokenIssuerTrust ...
 
JWT trusted issuers successfully set

    In the following example, CN=weblogic, OU=Orakey, O=Oracle, C=US' and CN=orcladmin, OU=Doc, O=Oracle, C=US' are set as DNs in the dns.jwt DN list for the www.yourcompany.com trusted JWT issuer:

    wls:/base_domain/serverConfig> setWSMTokenIssuerTrust('dns.jwt','www.yourcompany.com', 
['CN=weblogic, OU=Orakey, O=Oracle',
'CN=orcladmin, OU=Doc, O=Oracle, C=US'])
 
Starting Operation setWSMTokenIssuerTrust ...
 
JWT trusted issuers successfully set

  7. Display the trusted issuer and DN list using the displayWSMTokenIssuerTrust command.

    displayWSMTokenIssuerTrust(type, issuer=None)

    When you specify a value for the type and issuer arguments, the DN lists for the issuer are displayed. If you do not specify an issuer name, all of the trusted issuers for the given type are listed.

    For example, to view the DN lists for the www.yourcompany.com trusted issuer:

    wls:/base_domain/serverConfig> displayWSMTokenIssuerTrust('dns.jwt', 'www.yourcompany.com')
 
Starting Operation displayWSMTokenIssuerTrust ...
 
CN=weblogic, OU=Orakey, O=Oracle
CN=orcladmin, OU=Doc, O=Oracle, C=US

    To view all of the trusted issuers for the type dns.jwt:

    wls:/base_domain/serverConfig> displayWSMTokenIssuerTrust('dns.jwt')
 
Starting Operation displayWSMTokenIssuerTrust ...
 
www.yourcompany.com
www.oracle.com

  8. Write the current contents of this session to the OWSM Repository using the commitRepositorySession command.

    For example:

    wls:/base_domain/serverConfig> commitRepositorySession()

The tokenissuertrust trust_t1 is valid.
Creating tokenissuertrust trust_t1 in repository.
 
Repository session committed successfully.

Alternatively, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

For more information about these commands, see "Token Issuer Trust Configuration Commands" in WebLogic Scripting Tool Command Reference for Identity and Access Management.

6.3.5.2 Deleting a Trusted Issuer Using WLST

You can delete a trusted issue from a token issuer trust document in the repository using the deleteWSMTokenIssuerTrust command. The issuer must exist in the token issuer trust document selected in the session.

To delete a trusted issuer:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Start a repository session using the beginRepositorySession command.

    For example:

    wls:/base_domain/serverConfig> beginRepositorySession()

Repository session begun.

  3. List the token issuer trust documents in the repository using the listWSMTokenIssuerTrustDocuments command.

    listWSMTokenIssuerTrustDocuments(name=None, detail='false')

    When used without any arguments, all the token issuer trust documents in the repository are listed. If you set the detail argument to true, the display name and the status of the document are also displayed.

    For example:

    wls:/base_domain/serverConfig> listWSMTokenIssuerTrustDocuments(detail='true')
 
Name         : oracle-default
Display Name : Token Issuer Trust Properties
Status       : DOCUMENT_STATUS_COMMITED
 
Name         : trust_t1
Display Name : myinstance1 Trust Document
Status       : DOCUMENT_STATUS_COMMITED

  4. Select the document for modification that contains the trusted issuer to be deleted using the selectWSMTokenIssuerTrustDocument command. The name argument is required.

    selectWSMTokenIssuerTrustDocument(name)

    For example:

    wls:/base_domain/serverConfig> selectWSMTokenIssuerTrustDocument('trust_t1')
 
Token Issuer Trust document named "trust_t1" selected in the session.

  5. Optionally, display the trusted issuers defined in the trust document using the displayWSMTokenIssuerTrust command.

    displayWSMTokenIssuerTrust(type, issuer=None)

    For example, to display all the trusted issuers for the JWT token type:

    wls:/base_domain/serverConfig> displayWSMTokenIssuerTrust('dns.jwt') 
 
Starting Operation displayWSMTokenIssuerTrust ...
 
www.yourcompany.com
www.oracle.com

  6. Delete the desired token issuer, and its associated DN list if applicable, using the deleteWSMTokenIssuerTrust command.

    deleteWSMTokenIssuerTrust(type, issuer)

    For example, to delete the www.yourcompany.com trusted issuer for the JWT token type:

    wls:/base_domain/serverConfig> deleteWSMTokenIssuerTrust('dns.jwt','www.yourcompany.com')

Starting Operation deleteWSMTokenIssuerTrust ...
 
JWT trusted issuers deleted successfully.

  7. Write the contents of the current session to the repository using the commitRepositorySession command.

    wls:/base_domain/serverConfig> commitRepositorySession()
 
Repository session committed successfully.

    Alternatively, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

6.3.5.3 Deleting a Token Issuer Trust Document Using WLST

To delete a token issuer trust document from the repository:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Start a repository session using the beginRepositorySession command.

    For example:

    wls:/base_domain/serverConfig> beginRepositorySession()

Repository session begun.

  3. List the token issuer trust documents in the repository using the listWSMTokenIssuerTrustDocuments command.

    listWSMTokenIssuerTrustDocuments(name=None, detail='false')

    When used without any arguments, all the token issuer trust documents in the repository are listed. If you set the detail argument to true, the display name and the status of the document are also displayed.

    For example:

    wls:/base_domain/serverConfig> listWSMTokenIssuerTrustDocuments(detail='true')
 
Name         : oracle-default
Display Name : Token Issuer Trust Properties
Status       : DOCUMENT_STATUS_COMMITED
 
Name         : trust_t1
Display Name : myinstance1 Trust Document
Status       : DOCUMENT_STATUS_COMMITED

  4. Delete the desired token issuer trust document using the deleteWSMTokenIssuerTrustDocument command. The name argument is required.

    deleteWSMTokenIssuerTrustDocument(name)

    For example:

    wls:/base_domain/serverConfig> deleteWSMTokenIssuerTrustDocument('trust_t1')
Token Issuer Trust document named "trust_t1" deleted from the repository.

  5. Write the contents of the current session to the repository using the commitRepositorySession command.

    wls:/base_domain/serverConfig> commitRepositorySession()
 
Deleting tokenissuertrust trust_t1 from repository.
 
Repository session committed successfully.

    Alternatively, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

6.3.5.4 Exporting and Importing Trust Configuration Using WLST

You can export and import the trust configuration (Issuers, DNs, token attribute rules) between systems using the exportWSMTokenIssuerTrustMetadata and importWSMTokenIssuerTrustMetadata commands. These commands do not need to be run in a session.

When you export trust configuration, it is exported to an XML file at a location that you specify. You can export all trusted issuers, or exclude specific issuers. You can then copy the file to another system, and then import the trust metadata from the XML file.

Exporting Trust Configuration

To export trust metadata, use the exportWSMTokenIssuerTrustMetadata command.

exportWSMTokenIssuerTrustMetadata(trustFile,excludeIssuers=None)

In this command:

  • trustFile—Location of the XML file where the exported metadata will be stored.

  • excludeIssuers—Optional argument used to specify the list of issuers for which the trust metadata should not be exported.

For example, to export the trust metadata and exclude www.oracle.com, use the following command:

wls:/base_domain/serverConfig> exportWSMTokenIssuerTrustMetadata('/tmp/trustData.xml',['www.oracle.com'])
 
Starting Operation exportWSMTokenIssuerTrustMetadata ...
 
Configuration for trusted issuers successfully exported.

Importing Trust Configuration

To import the trust metadata for all trusted issuers, use the importWSMTokenIssuerTrustMetadata command.

importWSMTokenIssuerTrustMetadata(trustFile)

In this command:

  • trustFile—Location of the XML file from which the metadata will be imported.

For example, to import the trust metadata from the file /tmp/trustData.xml, use the following command:

wls:/base_domain/serverConfig> importWSMTokenIssuerTrustMetadata('/tmp/trustData.xml')
 
Starting Operation importWSMTokenIssuerTrustMetadata ...
 
Configuration for trusted issuers successfully imported.

6.3.5.5 Revoking Trust From Trusted Issuers Using WLST

You can revoke trust by removing trusted issuers and associated configurations (DNs and token attribute rules) using the revokeWSMTokenIssuerTrust WLST command. You can remove all trusted issuers, or specify specific issuers to be excluded from the list to be removed using the excludeIssuers argument. If no argument is passed, then all trusted issuers and their associated configuration are removed.

revokeWSMTokenIssuerTrust(excludeIssuers=None)

For example, to revoke the trust from all issuers except www.oracle.com, use the following command:

wls:/base_domain/serverConfig> revokeWSMTokenIssuerTrust(['www.oracle.com'])
 
Starting Operation revokeWSMTokenIssuerTrust ...
 
Configuration for trusted issuers successfully removed.

6.3.6 Configuring Message Security Using WLST

You can configure the MSAS keystore and message security settings such as clock skew and message expiration time using WLST commands. This configuration is described in the following sections:

6.3.6.1 Managing the MSAS Keystore Using Keystore Service Commands

The Keystore Service uses a dedicated set of command-line commands for keystore operations such as creating and managing keystores, exporting certificates, and generating keypairs. While their usage is similar, these commands are distinct from other WLST commands. Details about these commands and their usage is provided in "About Keystore Service Commands" in Securing Applications with Oracle Platform Security Services.

Before using the Keystore Service commands, you must execute the getOpssService command to obtain an OPSS service command object that enables you to execute the commands and get help.

The following procedure describes how to execute the keystore commands to manage the MSAS keystore.

  1. Connect to the running server as described in "Accessing the MSAS WLST Commands".

  2. Execute the getOpssService command to access the Keystore Service commands:

    wls:/base_domain/serverConfig>svc = getOpssService(name='KeyStoreService')

  3. Optionally, execute the help command svc.help to get a list of the available commands or help on a specific command. To get a list of the available commands, use svc.help(). To get help on a specific command, provide the command name as the argument. For example, to get help on the createKeyStore command, enter the following:

    wls:/base_domain/serverConfig> svc.help('createKeyStore')
Description:
Creates a new keystore. 

Syntax: 
svc.createKeyStore(appStripe='<stripe>', name='<keystore>', password='<password>',permission=true|false)
svc=the service command object obtained through a call to getOpssService() 
appStripe= the name of the stripe in which keystore is created.
name= the name of the keystore.
password= Password of the keystore. 
permission= true if keystore is protected by permission only, false if protected by both permission and password.

Example: svc.createKeyStore(appStripe='system', name='keystore1', password='<password>', permission=true)

  4. Create a new keystore using the createKeystore command:

    Note:

    The MSAS keystore is created automatically when you create an MSAS instance using the configMSAS script, or when you register a logical instance in the MSAS console. You only need to execute this command if you want to create the keystore before you create or register the instance.
    wls:/base_domain/serverConfig> svc.createKeyStore(appStripe='mynewinstance',name='keystore',password='',permission=true)
Already in Domain Runtime Tree
 
Keystore created

  5. To generate a keypair, use the generateKeyPair command.

    svc.generateKeyPair(appStripe='<stripe>', name='<keystore>', password='<password>', dn='<distinguishedname>', keysize='<keysize>', alias='<alias>', keypassword='<keypassword>')

    For example:

    wls:/base_domain/serverConfig> svc.generateKeyPair(appStripe='mynewinstance',name='keystore',password='',dn='cn=orakey',keysize='1024',alias='orakey',keypassword='')
Already in Domain Runtime Tree
 
Key pair generated

  6. Optionally, list the keystores configured in the environment for all instances using the listKeyStores command:

    wls:/base_domain/serverConfig> svc.listKeyStores(appStripe='*')
Already in Domain Runtime Tree
 
system/trust
system/castore
myinstance1/keystore
mynewinstance/keystore

  7. To import an existing JKS keystore into the KSS keystore, use the importKeyStore command:

    svc.importKeyStore(appStripe='<stripe>', name='<keystore>', password='<password>', aliases='<comma-separated-aliases>', keypasswords='<comma-separated-keypasswords>', type='<keystore-type>', permission=true|false, filepath='<absolute_file_path>')

    For example:

    wls:/base_domain/serverConfig> svc.importKeyStore(appStripe='mynewinstance',name='keystore',password='',aliases='orakey',keypasswords='orakey',type='JKS', permission=true,filepath='/path/default-keystore.jks')
Already in Domain Runtime Tree
 
Keystore imported. Check the logs if any entry was skipped.

6.3.6.2 Configuring the Signature and Encryption Keys in the MSAS Keystore Using WLST

When you create an MSAS instance, it creates the MSAS signature keystore by default, using the MSAS instance name as the stripe name, such as kss://myinstance/keystore. It also imports the necessary certificates and keys. Because this KSS keystore is defined at the instance level, the signature and encryption keys apply to all applications in the instance.

You can configure the encryption and signature keys for the MSAS keystore using the setMSASConfiguration command as described in "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance".

Table 6-2 lists the keystore properties that you can set to encryption and signature keys.

Table 6-2 MSAS Keystore Configuration Properties for an MSAS Instance

Category Property Name Default Description

KeystoreConfig

keystore.enc.csf.key

N/A

Alias of the key used to encrypt and decrypt messages.

KeystoreConfig

keystore.sig.csf.key

N/A

Alias of the key used for storing the signature key in the keystore.

KeystoreConfig

keystore.pass.csf.key

N/A

Reserved for future use.

KeystoreConfig

keystore.csf.map

N/A

The map in the CSF used to locate the MSAS Keystore specific credentials. This property should not be changed.

KeystoreConfig

keystore.type

N/A

This value is configured when the MSAS instance is registered with the Mobile Security Manager and should not be changed.

KeystoreConfig

location

N/A

Location of the KSS keystore: kss://msas_instance_name/keystore. This value is configured when you create the MSAS instance and should not be changed.

6.3.6.3 Configuring Security Settings Using WLST

To configure the security settings, use the setMSASConfiguration command as described in "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance".

Table 6-3 lists the MSAS instance-level configuration properties that you can set for security policy enforcement.

Table 6-3 Security Policy Enforcement Configuration Properties for an MSAS Instance

Category Property Name Default Description

Agent

client.clock.skew

0

Tolerance of time, in seconds, that is used to calculate the NotBefore and NotOnOrAfter conditions for SAML and JWT token generation. Together, these conditions define the lower and upper boundaries to limit the validity of the token.

Agent

clock.skew

360000

Tolerance of time differences between client and server machines. For example, when timestamps are sent across in a message to a service that follows a different time zone, this property allows for the specified time tolerance.

For more information about this property, see the description for the Clock Skew property in "Configuring Security Settings".

Agent

expire.time

300000

Duration of time before a message expires after its creation. This property is used in cases where a timestamp is sent across in the token to verify if the timestamp has expired or not.

For more information about this property, see the description for the Message Expiration Time property in "Configuring Security Settings".

Agent

compliance.check

true

Reserved for future use.

Agent

nonce.ttl

28800000

Reserved for future use.

Agent

allow.all.xpaths

false

Reserved for future use.

Agent

use.unified.fault.code

true

Reserved for future use.

6.3.7 Configuring the Cache Refresh Time Using WLST

To configure cache management, use the setMSASConfiguration command as described in "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance".

Table 6-4 lists the MSAS-instance level configuration properties that you can set to configure the policy cache.

Table 6-4 Cache Management Configuration Properties for an MSAS Instance

Category Property Name Default Description

BeanAccessor

cache.refresh.repeat

86400000

The number of milliseconds to wait between cache refreshes.

BeanAccessor

cache.refresh.initial

600000

Reserved for future use.

BeanAccessor

failure.retry.count

2

Reserved for future use.

BeanAccessor

cache.refresh.batch.size

10

Reserved for future use.

BeanAccessor

failure.retry.delay

5000

Reserved for future use.

BeanAccessor

missing.retry.delay

15000

Reserved for future use.

BeanAccessor

usage.record.delay

30000

Reserved for future use.

6.3.8 Configuring the Authentication Endpoints Using WLST

You can configure the authentication endpoints used for initial authentication using the setMSASConfiguration command as described in "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance".

The following sections describe the configuration properties for the different authentication endpoints.

6.3.8.1 Configuring the KINIT and PKINIT Authentication Endpoint Using WLST

Table 6-5 lists the configuration properties that you can set to configure KINIT and PKINIT authentication for the MSAS instance.

Table 6-5 KINIT/PKINIT Configuration Properties for an MSAS Instance

Category Property Name Default Description

Krb5Configuration

default_realm

N/A

Name of the realm to be used as the default realm.

Krb5Configuration

default_tkt_enctypes

N/A

Session key encryption type that the client should use when making an initial authentication request (AS-REQ). For a list of the supported types, refer to the MIT Kerberos Documentation, "Encryption types" at http://web.mit.edu/Kerberos/krb5-1.12/doc/admin/conf_files/kdc_conf.html#encryption-types.

Krb5Configuration

default_tgs_enctypes

N/A

Session key encryption type that the client should use when requesting a service ticket from the TGS (TGS_REQ). For a list of the supported types, refer to the MIT Kerberos Documentation, "Encryption types" at http://web.mit.edu/Kerberos/krb5-1.12/doc/admin/conf_files/kdc_conf.html#encryption-types.

Krb5Configuration

pkinit_anchors

N/A

Trust anchors that the KDC will use when evaluating the trust of the client certificate.

pkinit_anchors points to the keystore alias which should be the first certificate in the certificate chain. This is a mandatory property when PKINIT is used.

Krb5Configuration

pkinit_anchors_file

N/A

Reserved for internal use.

Krb5Configuration

logging.krb5

N/A

Log location for the Kerberos configuration messages. Valid options are STDERR or a log file name and path.

Krb5Configuration

logging.kcm

N/A

Log location for the KCM configuration messages. Valid options are STDERR or a log file name and path.

Krb5Configuration

realms.kdc

N/A

Name for the Kerberos realm. The realm name must match the REALM name defined in the Active Directory setup.

Krb5Configuration

realms.default_domain

N/A

Default domain for the realm. Typically the domain name is in lower case, for example example.com.

Krb5Configuration

domain

N/A

DNS domain name.

6.3.8.2 Configuring the OAuth2 Confidential Client Endpoint Using WLST

Table 6-6 lists the configuration properties that you can set to configure OAuth2 Confidential Client authentication for the MSAS instance.

Table 6-6 OAuth2 Confidential Client Configuration Property for an MSAS Instance

Category Property Name Default Description

OAuth2ConfidentialClientConfiguration

service.profile.endpoint

N/A

OAuth Service Profile Endpoint to which the MSAS server creates JWT User Token and OAM Tokens for OAuth2 Confidential Client Authentication flow.

For example: http://host:port/ms_oauth/oauth2/endpoints/oauthservice

6.3.8.3 Configuring the OAuth2 Mobile Client Endpoint Using WLST

Table 6-7 lists the configuration properties that you can set to configure OAuth2 Mobile Client authentication for the MSAS instance.

Table 6-7 OAuth2 Mobile Client Configuration Property for an MSAS Instance

Category Property Name Default Description

OAuth2MobileClientConfiguration

service.profile.endpoint

N/A

OAuth Service Profile Endpoint to which the MSAS server creates JWT User Token and OAM Tokens for OAuth2 Mobile Client Authentication flow.

For example: http://host:port/ms_oauth/oauth2/endpoints/oauthservice

6.3.8.4 Configuring the Crypto Service Endpoint Using WLST

Table 6-7 lists the configuration properties that you can set to configure the key rollover feature in the PKI Crypto Service for the MSAS instance.

Table 6-8 Crypto Service Configuration Property for an MSAS Instance

Category Property Name Default Description

CryptoServiceConfiguration

archive.key.aliases

N/A

Alias for the keystore containing archived private keys to be used by the key rollover feature. If left unset, the key rollover support feature is not enabled. If you enter an alias in this field, key rollover is enabled, and the alias specified is added to the list of aliases used by the rollover feature. A decryption error will not be returned by the crypto service unless decryption of a given ciphertext fails with all archived private keys.

6.3.9 Configuring System Settings Using WLST

You can configure system settings such as outbound message settings, proxy servers, load balancing, and SSL using WLST setMSASConfiguration command as described in "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance".

The following sections describe the configuration properties that you can set for the different system settings.

6.3.9.1 Configuring Outbound Message Settings Using WLST

Table 6-9 lists the configuration properties that you can set to configure outbound message settings for an MSAS instance.

Table 6-9 Outbound Message Setting Properties for an MSAS Instance

Category Property Name Default Description

ClientConfiguration

max.connection.pool.per.host

25

Maximum number of connections in a pool, per host, that a client can handle.

ClientConfiguration

max.connection.pool.total

512

Maximum number of connections in a pool that a client can handle.

ClientConfiguration

idle.connection.pool.timeout

180000

Maximum time in milliseconds a client will keep idle connections in the pool.

ClientConfiguration

connection.timeout

20000

Maximum time in milliseconds a client can wait when connecting to a back-end host.

ClientConfiguration

request.timeout

60000

Maximum time in milliseconds a client can wait for a response.

ClientConfiguration

request.longtimeout

1200000

Maximum time in milliseconds that a client can wait for a response.

ClientConfiguration

max.request.retry

5

Number of times a request will be retried before an error occurs because of a network exception.

ClientConfiguration

ssl.security.level

loose

SSL security level for outbound calls to back-end resources. For more information, see "Configuring SSL Between MSAS and Back-End Resources".

6.3.9.2 Configuring Proxy Server Settings Using WLST

Table 6-10 lists the configuration properties that you can set to configure the proxy server used for outbound calls to the internet through MSAS for back-end applications and services.

Table 6-10 Proxy Server Configuration Properties for an MSAS Instance

Category Property Name Default Description

ProxyServer

name

N/A

Name of proxy server to uniquely identify it.

ProxyServer

host

N/A

Host name of proxy server.

ProxyServer

port

N/A

Port number of proxy server.

ProxyServer

csf.key

N/A

Name of the CSF key that has credentials for authenticating to the proxy server. This property is optional.

ProxyServer

non.proxy.hosts

localhost

127.0.0.1

List of hosts that will not use the proxy server. It supports the asterisk * wildcard, but only as a suffix and prefix.

6.3.9.3 Configuring Server Settings Using WLST

Table 6-11 lists the configuration properties such as load balancing URLs and service principal name mapping that you can set for an MSAS instance to configure the server.

Table 6-11 Server Configuration Properties for an MSAS Instance

Category Property Name Default Description

ServerSettings

spn.mapping

N/A

Maps a URL with Service Principal Name. Service Principal Name is required for NTLM and SPNEGO. URL supports wildcard using "*" and can go anywhere in the URL, for example, http*://example.host*80/* or *.example.org. SPN should be in form of <SPN_SERVICECLASS>/<SPN_HOSTNAME>."

ServerSettings

lbr.url

N/A

Non-SSL URL for a front ending load balancer, for example http://lbr.example.org:80.

ServerSettings

lbr.ssl.url

N/A

SSL URL for a front-ending load balancer, for example https://lbr.example.org:443.

6.3.9.4 Configuring SSL Settings Using WLST

Table 6-12 lists the configuration properties that you can set to specify the location of the SSL keystore and truststore for an MSAS instance.

Table 6-12 SSL Configuration Properties for an MSAS Instance

Category Property Name Default Description

ServerSettings

ssl.truststore.location

N/A

Location of SSL trust store. Only KSS keystore type is supported so the value must be a KSS URI.

ServerSettings

ssl.keystore.location

N/A

Location of the SSL keystore used for inbound SSL connections to MSAS and as the MSAS identity keystore. Only KSS keystore type is supported so the value must be a KSS URI.

6.3.9.5 Configuring Access Log Settings Using WLST

Table 6-12 lists the configuration properties that you can set to enable or disable access logs for the MSAS instance.

Table 6-13 SSL Configuration Properties for an MSAS Instance

Category Property Name Default Description

ServerSettings

access.log.enabled

true

Enables or disables the access logs for the MSAS server. By default, this property is enabled. For more information about access logs, see "Configuring MSAS Access Logs".

ServerSettings

access.log.format

N/A

Reserved for future use.

6.3.10 Configuring the SToken Expiry Time

By default, the session token (SToken) expiry time is set to 34800000ms (approximately 9.6 hours). You can adjust the SToken expiry time using the setMSASConfiguration WLST command as described in "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance", using MSASConfig as the CategoryName and stoken.expiry.time as the propertyName.

For example, to change the SToken expiry time to 5 minutes, use the following command:

setMSASConfiguration('myinstance1','MSASConfig', 'stoken.expiry.time', None, ['300000'])

Note the following:

  • The expiry time and skew time give an actual expiration for an SToken.

  • The SToken expiry time that you configure cannot exceed the maximum expiry time set by any token except the KINIT/PKINIT SToken.

  • The limit for the KINIT/PKINIT SToken maximum expiry time can be set as the default expiry time.

6.3.11 Configuring the MSAS Heartbeat Using WLST

The heartbeat is a process used to check if an MSAS instance is running normally and is reacting to the heartbeat polling requests (reliable UDP protocol). It is a standalone process that runs on each machine that is hosting one or more MSAS instances. By default, if an MSAS instance is dead or is not responding to heartbeat requests for any reason, the heartbeat process will try to restart that target instance.

The heartbeat process runs completely in the background. When the first MSAS instance is started on the host machine, the heartbeat process is started silently and registers the MSAS instance so that it can send polling messages. When additional instances are started on that machine, they are registered into the same heartbeat process. The polling and restart behavior is targeted per instance on each machine. When an individual instance is stopped, (stopServer.sh), the heartbeat process will unregister that instance from its polling group. If all instances on a machine are stopped, the heartbeat process quits.

The heartbeat process is configuration driven. All of the heartbeat configuration properties are managed by the Mobile Security Manager (MSM) at the logical instance level. You configure the MSAS heartbeat using the setMSASConfiguration WLST command as described in "Using the setMSASConfiguration WLST Command to Configure an MSAS Instance".

The Mobile Security Manager should be installed and running before updating the heartbeat configuration. Table 6-14 lists the configuration properties that you can set to configure the MSAS heartbeat.

Table 6-14 Heartbeat Configuration Properties for an MSAS instance

Category Property Name Default Description

MSASConfig

heartbeat.enabled

true

Flag used to enable or disable the heartbeat function.

MSASConfig

heartbeat.restartEnabled

true

Controls whether to restart the MSAS instance if the number of failures exceeds the threshold (value set for heartbeat.maxRetry).

MSASConfig

heartbeat.port

7777

Local listening port for registering MSAS instances and MSAS responses.

MSASConfig

heartbeat.frequency

5

The frequency, in seconds, to send heartbeat requests.

MSASConfig

heartbeat.maxRetry

5

Maximum number of retries if there no response from the MSAS instance.

MSASConfig

heartbeat.logFileName

heartbeat.log

Log file name for the heartbeat process. The heartbeat log file is created in the following directory:

instance_root/instance_name/log

MSASConfig

heartbeat.logLevel

20

Log level for the heartbeat. When set to 20 (coarse logging) only messages such as MSAS register/deregister or a target instance being restarted are logged. For finer grained logging for debugging purposes, set this value to 10. In this case, every heartbeat message is logged.

6.3.12 Configuring Additional Server Settings Using WLST

Table 6-15 lists the configuration properties for additional server settings that you can set using the setMSASConfiguration command.

Table 6-15 Configuration Properties for Additional Server Settings

Category Property Name Default Description

MSASConfig

msm.csf-key

N/A

Reserved for internal use.

MSASConfig

msm.url

N/A

Reserved for internal use.

MSASConfig

msas.id

N/A

Reserved for internal use.

MSASConfig

sync.interval

60000

Maximum time in milliseconds for the server to check for a synchronization event. The synchronization event is generated when the Synchronize button corresponding to the MSAS instance in clicked in the MSAS console. For more information about using the Synchronize button, see "Synchronizing MSAS Instance Configuration".

MSASConfig

server.workerThread.corePoolSize

8

Core thread pool size.

MSASConfig

server.workerThread.maxPoolSize

1024

Maximum thread pool size.

MSASConfig

server.keepAlive

true

HTTP connection keep alive.

MSASConfig

server.readBufferSize

40960

Read buffer size, in bytes, for HTTP connection.

MSASConfig

server.writeBufferSize

16384

Write buffer size, in bytes, for HTTP connection.

MSASConfig

server.connectionTimeout

16384

Timeout, in milliseconds, when connecting to the server. The request will wait for the specified time before it times out due to a connection error.

MSASConfig

server.socketTimeout

180000

Timeout, in milliseconds, in server socket wait time.

MSASConfig

server.writeTimeout

180000

Write timeout, in milliseconds, for the server to write back to clients. Increase it if there are slower clients but increasing it too much will have an effect on connections.

MSASConfig

server.connectionBacklog

4096

Number of connections allowed in the backlog.

MSASConfig

server.clientSocketTimeout

180000

Timeout, in milliseconds, in client socket wait time.

MSASConfig

server.http.maxRequestHeaderSize

32768

Max request header size, in bytes.

MSASConfig

security.clientAuthenticationRequired

NO

Client authentication required. Valid values:

  • YES—Client authentication required.

  • NO—Client authentication not required.

  • MAY—Client authentication optional.

MSASConfig

security.keystoreAlias

msasidentity

Keystore alias.

6.3.13 Configuring the Credential Store Using WLST

You can create, update, and delete credentials in the credential store using WLST commands.

To use WLST commands to configure the credential store:

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. To create a credential in the credential store, use the createCred command.

  3. createCred(map="<mapname>", key="<keyname>", user="<userName>", password="<password>",[desc="<description>"])

    In this command:

    • map—Specifies a map name or folder in the credential store. For MSAS, this is the MSAS instance name. This field is required.

    • key—Specifies a key name.

    • user—Specifies the credential user name.

    • password—Specifies the credential password.

    • description—Description of the credential. This argument is optional.

    For example:

    wls:/base_domain/serverConfig> createCred('myinstance1','key','demoUser','demoPassword')

  4. To update a credential in the credential store, use the updateCred command.

    updateCred(map="<mapname>", key="<keyname>", user="<userName>", password="<password>", desc="<description>")

    In this command:

    • map—Specifies a map name or folder in the credential store. For MSAS, this is the MSAS instance name. This field is required.

    • key—Specifies a key name.

    • user—Specifies the credential user name.

    • password—Specifies the credential password.

    • description—Description of the credential. This argument is optional.

    For example:

    wls:/base_domain/serverConfig> updateCred('myinstance1','demoKey','demoUser','newPassword')

  5. To delete a credential from the credential store, use the deleteCred command.

    deleteCred(map="<mapname>", key="<keyname>")

    In this command:

    • map—Specifies a map or folder in the credential store. For MSAS, this is the MSAS instance name.

    • key—Specifies a key name.

    For example, to delete a credential with map name myinstance1 and key name demoKey:

    wls:/base_domain/serverConfig>  deleteCred('myinstance1','demoKey')

For more information about these commands, see the following topics:

6.4 Advanced Kerberos Configuration

You can use the MSAS console pages to configure the properties of the Kerberos krb5.conf file to enable KINIT and PKINIT authentication. You can add, edit, and delete Kerberos realms, add and delete DNS domains, specify Kerberos encryption types, specify the logging location for the Kerberos and KCM messages, and enable the use of PKINIT trust anchors. For details, see "Configuring KINIT and PKINIT Authentication."

However, if you need more advanced configuration and customization, you must create the krb5.conf file manually. For example, you may need to customize the file to point to specific domain controllers or to accommodate environments with alternate UPN suffixes. Once you save this file, the changes are persisted and it takes precedence over the file created using the console.

Note:

You should only create the krb5.conf file as described in this section if advanced configuration is required. Updates to this file are not supported by the MSAS console, therefore any changes that you make using the console are ignored.

Do not manually edit the krb5.conf file in the instance_name/config directory as that is intended for use only by the MSAS console.

The following sections describe how to create and edit the file in these situations.

6.4.1 Creating the Kerberos Configuration File Manually

To create the krb5.conf file:

  1. Create a default directory under the following location:

    instance_root/instance_name/config/

    where instance_root is the root directory you specified when you created the instance, and instance_name is the name of the instance. By default, instance_root is MW_HOME/instances, and MW_HOME is the Middleware home directory in which you installed Mobile Security Access Server.

    For example, /home/instances/myinstance1/config/default

  2. Create a krb5.conf file using the settings required for your environment as described in the MIT Kerberos Documentation at http://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html.

    For example:

    [libdefaults]
  default_realm = EXAMPLE.COM
  default_tkt_enctypes = arcfour-hmac-md5
  default_tgs_enctypes = arcfour-hmac-md5
  kdc_timeout = 30
  max_retries = 1
  
[appdefaults]
  pkinit_anchors = FILE:instance_root/instancename/config/pkinit_anchors.cer
  
[logging]
  krb5 = STDERR
  kcm = STDERR
 
[realms]
  EXAMPLE.COM = {
  kdc = example.com
  default_domain = example.com
  }
 
[domain_realm]
  .example.com = EXAMPLE.COM

  3. Save the krb5.conf file to the instance_root/instance_name/config/default directory that you created in step 1.

    Note that once you create and save the krb5.conf file to this directory, it takes precedence over the one created using the console and any subsequent updates using the console are ignored.

6.4.2 Adding Multiple Active Directory Domains

To add additional Active Directory forests and domains, edit the Kerberos configuration file that you created manually at instance_root/instance_name/config/default/krb5.conf and add the realms to the realms section and the domain-to-realm mapping to the domain_realm section using the following syntax.

[realms]
  <KRB_REALM_NAME> = {
  kdc = <domain_name>
  default_domain = <domain_name>
  }
 
[domain_realm]
 .<domain_name> = <KRB_REALM_NAME>

For example:

 [realms]
  EXAMPLE1.COM = {
  kdc = example1.com
  default_domain = example1.com
  }
  EXAMPLE2.COM = {
  kdc = example2.com
  default_domain = example2.com
  }
[domain_realm]
  .example1.com = EXAMPLE1.COM
  .example2.com = EXAMPLE2.COM

6.4.3 Targeting Specific Domain Controllers

By default, after installation Mobile Security Access Server is configured to find the domain controllers for a specific domain by doing a DNS look up. The entries in the realms section for each domain in the instance_root/instance_name/config/default/krb5.conf file will look something like the following:

EXAMPLE.COM={
  kdc=example.com
  default_domain=example.com
}

You can configure Mobile Security Access Server to point to specific domain controllers for a given domain. Use a separate kdc line for each domain controller. For example:

EXAMPLE.COM = {
  kdc = dc1.example.com
  kdc = dc2.example.com
  default_domain = example.com
}

By default when there are multiple domain controllers configured, Mobile Security Access Server will try each of them in order. You can configure Mobile Security Access Server to try the individual domain controllers in random order by adding the statement random_fallback = true to the realm configuration. For example:

EXAMPLE.COM = {
  kdc = dc1.example.com
  kdc = dc2.example.com
  random_fallback = true
  default_domain = example.com
}

6.4.4 Adding Alternate UPN Suffixes

An alternate User Principal Name (UPN) suffix occurs when the domain in the UPN after the @ symbol is different from the Windows domain where the user resides, or any other Windows domain that can refer authentication requests to the user's domain.

For environments using accounts with alternate UPN suffixes and Windows password (KINIT), it is necessary to configure Mobile Security Access Server to perform Kerberos authentication using what are known as Enterprise Accounts. To turn on support for alternate UPN suffixes:

  1. Open and edit the krb5.conf file at in the following location:

    instance_root/instance_name/config/default/krb5.conf

  2. Add the following configuration line at the end of the libdefaults section:

    [libdefaults
....]
   enterprise=true

    Note:

    When using this flag it is important to set the default_realm parameter in the libdefaults section to point to the root domain that is below all sub-domains that contain users that need to authenticate.

    For example, for a Windows forest comprised of a root domain example.com with two sub-domains sub1.domain.com and sub2.domain.com, the default_realm parameter should be set to example.com."

6.5 Manually Configuring OAuth2 Client Authentication

For the Mobile Security Access Server to authenticate users against Oracle Access Manager and retrieve Oracle Access Manager and OAuth tokens for integrated single sign on, the Mobile Security Access Server must be registered as an OAuth Confidential Client with the Oracle Access Manager OAuth Service. This configuration is completed automatically when you configure an MSAS instance using the Mobile Security Access Server configuration script, configMSAS.

However, you can also perform this configuration using the Oracle Access Management console and WLST. You can also use the procedures described in these sections to verify that the configuration is completed properly.

The following sections describe how to do so.

6.5.1 Configuring OAuth2 Confidential Client Authentication

There are three primary steps to configuring OAuth2 Confidential Client authentication.

Step 1. Create the OAuth2 Confidential Client Profile

  1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

  2. Click the Mobile OAuth Services icon. The Mobile OAuth Identity Domains page opens in a new tab.

  3. Select the Default Domain in the table. The Mobile Identity Domain Configuration page opens in a new tab.

  4. Click Clients, then in the OAuth Web Clients section, click the Create icon. The OAuth Web Client Configuration page opens in a new tab.

  5. Enter a name, client ID, and client secret in the appropriate fields.

    Field Description
    Name Enter a name for the OAuth client using the format MSAS_Instance_ID_MSASClient, for example myinstance1_MSASClient.
    Client ID Enter a client ID using the format MSAS_Instance_ID_MSASClient, for example myinstance1_MSASClient.
    Client Secret Enter a password for the client. Make note of the password because you will need to provide it when configuring the credential store.

  6. Expand the Privileges section, if it is not already expanded.

  7. Select Allow access to all scopes, then in the Grant Types section, select Resource Owner Credentials, JWT Bearer, and OAM Credentials. The OAuth Web Client Configuration page is shown in Figure 6-5.

    Figure 6-5 OAuth Web Client Configuration Page

    Description of Figure 6-5 follows
    Description of "Figure 6-5 OAuth Web Client Configuration Page"

    For detailed information about this page, see "Understanding the Mobile Clients Configuration Page" in Administrator's Guide for Oracle Access Management.

  8. Click Create at the top of the page.

Step 2. Configure OAuth2 Confidential Client Service Profile Endpoint in the MSAS Instance

  1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

  2. In the Mobile Security Access Server section, click Environments.

    The MSAS Environments page opens in a new tab.

  3. Click MSAS or Instances in the MSAS tile.

    The MSAS Instances Summary page opens in a new tab.

  4. Click the instance name or Configure in the tile for the desired instance.

    The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  5. Click the Authentication Endpoints tab.

  6. In the OAuth2 Confidential Client section, enter the Service Profile Endpoints for the OAuth2 Confidential Client in the Endpoint field. For example: http://host:port/ms_oauth/oauth2/endpoints/oauthservice.

  7. Click Apply at the top of the page.

Step 3. Add OAuth2 Confidential Client Credential to the CSF Using WLST

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Use the createCred WLST command to add the confidential client credential created in the previous steps to the credential store.

    createCred(map="<mapname>", key="<keyname>", user="<userName>", password="<password>",[desc="<description>"])

    For example, to add the credential for the instance named myinstance1, using the key oauth2.confidential.client.credentials with the client ID/password as myinstance1_MSASClient/password1, and the description as OAuth2 Confidential Client Credential:

    createCred('myinstance1','oauth2.confidential.client.credentials','myinstance1_MSASClient','password1','OAuth2 Confidential Client Credential')

    The username and password specified here must match the client ID and secret key that you provided when creating the OAuth web clients.

6.5.2 Configuring OAuth2 Mobile Client Authentication

There are three primary steps to configuring OAuth2 Mobile Client authentication.

Step 1. Create the OAuth2 Mobile Client Profile

  1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

  2. Click the Mobile OAuth Services icon. The Mobile OAuth Identity Domains page opens in a new tab.

  3. Select the Default Domain in the table. The Mobile Identity Domain Configuration page opens in a new tab.

  4. Click Clients, then in the OAuth Mobile Clients section, click the Create icon. The OAuth Mobile Client Configuration page opens in a new tab.

  5. In the Name and Client ID fields, enter a name and client ID using the format MSAS_Instance_ID_OracleContainer, for example myinstance1_OracleContainer.

  6. Expand the Privileges section, if it is not already expanded.

  7. Select Allow access to all scopes, then in the Grant Types section, select the following options:

    • Resource Owner Credentials

    • Client Credentials

    • JWT Bearer

    • OAM Credentials

    • Client Verification Code

    For detailed information about this page, see "Understanding the Mobile Clients Configuration Page" in Administrator's Guide for Oracle Access Management.

  8. Expand the Mobile Service Settings section and perform the following configuration:

    • Select Override the default settings.

    • In Supported Platforms, select iOS and Android.

    • For iOS Security Level, select Standard.

    • Clear the Enable Server Side Single-Sign-On checkbox.

  9. Click Create at the top of the page.

Step 2. Configure OAuth2 Mobile Client Service Profile Endpoint in the MSAS Instance

  1. From the Oracle Access Management home page, select the Mobile Security tab from the list of tabs at the top of the page.

  2. In the Mobile Security Access Server section, click Environments.

    The MSAS Environments page opens in a new tab.

  3. Click MSAS or Instances in the MSAS tile.

    The MSAS Instances Summary page opens in a new tab.

  4. Click the instance name or Configure in the tile for the desired instance.

    The MSAS Instance Configuration page displays in a new tab. The tab name is the name of the instance.

  5. Click the Authentication Endpoints tab.

  6. In the OAuth2 Mobile Client section, enter the Service Profile Endpoints for the OAuth2 Mobile Client in the Endpoint field. For example: http://host:port/ms_oauth/oauth2/endpoints/oauthservice.

  7. Click Apply at the top of the page.

Step 3. Add OAuth2 Mobile Client Credential to the CSF Using WLST

  1. Start WLST as described in "Accessing the MSAS WLST Commands".

  2. Use the createCred WLST command to add the OAuth mobile client credential created in the previous steps to the credential store.

    For example, to add the mobile client credential for the instance named myinstance1, using the key oauth2.mobile.client.id with the client ID as myinstance1_OracleContainer, any value for the password since the password is not used for Mobile Client authentication, and the description as OAuth2 Mobile Client Credential:

    createCred('myinstance1','oauth2.mobile.client.id','myinstance1_OracleContainer','myinstance1_OracleContainer','OAuth2 Mobile Client Credential')

    The Client ID used in this command must match the Client ID that you used when you created the OAuth2 Mobile Client as described in Step 1, in this example myinstance1_OracleContainer. The password can be any value as it is not used in this configuration.

6.6 Configuring Single Sign-On (SSO) for OAM WebGate and Oracle WSM Protected Resources

If your environment includes resources protected by Oracle Web Services Manager (Oracle WSM) and/or WebGates for Oracle Access Manager (OAM), you can configure Mobile Security Access Server to provide single sign-on capability for those resources. The procedure is described in the following steps.

Step 1: Create an MSAS Instance

You can create and configure an MSAS instance using the configMSAS command as described in "Configuring an MSAS Instance" in Installing Oracle Mobile Security Access Server.

Step 2: Configure the OAuth2 Confidential and Mobile Client Endpoints

You can configure the OAuth2 endpoints using the MSAS console pages as described in the following sections:

When configuring the authentication endpoint URL, you must enter the complete URL for the external OAuth server, for example:

http://example.com:14100/ms_oauth/oauth2/endpoints/oauthservice

Step 3: Create a forward proxy application for the Oracle Access Manager login page and secure it with access policies

To do so:

  1. Create a forward proxy application as described in "Creating a Proxy Application".

  2. In the application, define a proxy URL for the Oracle Access Manager login page. In the Host URL field, enter the URL for the OAM login page, for example:

    http://host:port/oam/server

  3. Select the URL, and attach the following policies to the policy enforcement endpoints as described in "Attaching Policies and Assertions to Proxy Applications":

    • On-Request—oracle/http_session_token_verify_policy

    • Invoke-Proxy—oracle/http_bmax_oam_client_policy

    For details about these policies, see "oracle/http_session_token_verify_policy" and "oracle/http_bmax_oam_client_policy" in Policy and Assertion Template Reference for Oracle Mobile Security Access Server.

Step 4: Ensure that a forward proxy application exists for single-sign-on to OAM WebGate protected resources

When you create an MSAS instance, a reserved application named Default URL is created to protect all forward proxy requests by default. If you have not modified or deleted this application, your WebGate protected resources will be protected by the policies attached to the Default URL application. If you have modified or deleted this application, then you need to create a forward proxy application and attach specific policies to the policy enforcement endpoints as follows:

  1. Create a forward proxy application as described in "Creating a Proxy Application".

  2. In the application, define a proxy URL for the WebGate.

  3. Select the URL, and attach the following policies to the policy enforcement endpoints as described in "Attaching Policies and Assertions to Proxy Applications":

    • On-Request—oracle/http_session_token_verify_policy

    • Invoke-Proxy—oracle/multi_token_client_policy

    For details about these policies, see "oracle/http_session_token_verify_policy" and "oracle/multi_token_client_policy" in Policy and Assertion Template Reference for Oracle Mobile Security Access Server.

Step 5: Ensure that a forward proxy application exists for single-sign-on to Oracle WSM protected resources

When you create an MSAS instance, a reserved application named Default URL is created to protect all forward proxy requests by default. If you have not modified or deleted this application, your Oracle WSM protected resources will be protected by the policies attached to the Default URL application. If you have modified or deleted this application, then you need to create a forward proxy application and attach specific policies to the policy enforcement endpoints as follows:

  1. Create a forward proxy application as described in "Creating a Proxy Application".

  2. In the application, define a proxy URL for the Oracle WSM-protected resource.

  3. Select the URL, and attach the following policies to the policy enforcement endpoints as described in "Attaching Policies and Assertions to Proxy Applications":

    • On-Request—oracle/http_session_token_verify_policy

    • Invoke-Proxy—attach one of the following:

      • oracle/multi_token_client_policy—This should be the default policy if Oracle WSM has been configured to trust OAuth/JWT tokens issued by Oracle Access Manager.

      • oracle/http_jwt_token_client_policy—This policy can be used in advanced configurations where Oracle WSM has been configured to trust JWT tokens issued by MSAS.

    For details about these policies, see "oracle/http_session_token_verify_policy" and "oracle/multi_token_client_policy"in Policy and Assertion Template Reference for Oracle Mobile Security Access Server and "oracle/http_jwt_token_client_policy" in Security and Administrator's Guide for Web Services.

6.7 Configuring Single Sign-On for Kerberos and NTLM Protected Resources

If your environment includes resources protected by Kerberos and/or NTLM, you can configure Mobile Security Access Server to provide single sign-on capability for those resources. The procedure is described in the following steps.

Step 1: Create an MSAS Instance

You can create and configure an MSAS instance using the configMSAS command as described in "Configuring an MSAS Instance" in Installing Oracle Mobile Security Access Server.

Step 2: Configure the Kerberos Authentication Endpoints

You can configure the Kerberos authentication (KINIT and/or PKINIT) endpoints using the MSAS console pages as described in the following sections:

Step 3: Ensure that a forward proxy application exists for single-sign-on to Kerberos protected resources

When you create an MSAS instance, a reserved application named Default URL is created to protect all forward proxy requests by default. If you have not modified or deleted this application, your Kerberos protected resources will be protected by the policies attached to the Default URL application. If you have modified or deleted this application, then you need to create a forward proxy application and attach specific policies to the policy enforcement endpoints as follows:

  1. Create a forward proxy application as described in "Creating a Proxy Application".

  2. In the application, define a proxy URL for the Kerberos protected resource.

  3. Select the URL, and attach the following policies to the policy enforcement endpoints as described in "Attaching Policies and Assertions to Proxy Applications":

    • On-Request—oracle/http_session_token_verify_policy

    • Invoke-Proxy—attach one of the following:

      • oracle/multi_token_client_policy

      • oracle/http_bmax_spnego_client_policy

For reference information about these policies, see "oracle/http_session_token_verify_policy", "oracle/multi_token_client_policy", and "oracle/http_bmax_spnego_client_policy" in Policy and Assertion Template Reference for Oracle Mobile Security Access Server.

Step 4: Ensure that a forward proxy application exists for single-sign-on to NTLM protected resources

When you create an MSAS instance, a reserved application named Default URL is created to protect all forward proxy requests by default. If you have not modified or deleted this application, your NTLM protected resources will be protected by the policies attached to the Default URL application. If you have modified or deleted this application, then you need to create a forward proxy application and attach specific policies to the policy enforcement endpoints as follows:

  1. Create a forward proxy application as described in "Creating a Proxy Application".

  2. In the application, define a proxy URL for the NTLM protected resource.

  3. Select the URL, and attach the following policies to the policy enforcement endpoints as described in "Attaching Policies and Assertions to Proxy Applications":

    • On-Request—oracle/http_session_token_verify_policy

    • Invoke-Proxy—attach one of the following:

      • oracle/multi_token_client_policy

      • oracle/http_ntlm_token_client_policy

For reference information about these policies, see "oracle/http_session_token_verify_policy", "oracle/multi_token_client_policy", and "oracle/http_ntlm_token_client_policy" in Policy and Assertion Template Reference for Oracle Mobile Security Access Server.

6.8 Configuring an MSAS Instance as a WebGate

Mobile Security Access Server can be configured to serve as a WebGate in your environment. A WebGate is a web-server plug-in for Oracle Access Manager (OAM) that intercepts HTTP requests and protects resources by URL. When you create and configure an MSAS instance using the configMSAS tool as described in "Configuring an MSAS Instance" in Installing Oracle Mobile Security Access Server, a WebGate profile is automatically created using the responses that you provide to the OAM prompts. This WebGate profile specifies which resources will be protected by OAM. To configure the MSAS instance to act as a WebGate, you attach an OAM security policy to virtual and proxy applications in the instance.

The high-level flow in this scenario is as follows:

  • The MSAS instance receives an HTTP request for access to a URL resource.

  • If the resource is protected by the predefined OAM policy, MSAS routes the request to OAM for authentication.

  • OAM presents its login page to the user for authentication.

  • User provides credentials and OAM authenticates the user against the configured identity store.

  • If the user is authenticated, OAM creates a session and sends an authentication response with a session token to MSAS.

  • MSAS allows user access to the resource.

To configure MSAS as a WebGate, you must attach the predefined OAM security policy to the URL resources defined in virtual and proxy applications in the instance. To do so:

  1. Create a virtual or proxy application in the instance as described in the following sections:

  2. Open the URL Policy Configuration page for the resource to be protected as described in the following sections:

  3. Attach the following policy to the On-Request endpoint for the URL:

    oracle/http_oam_authentication_service_policy

    For details about this policy, see "oracle/http_oam_authentication_service_policy" in Policy and Assertion Template Reference for Oracle Mobile Security Access Server.

  4. Click Validate, then Apply to save the changes.

Note:

If you need to update the WebGate profile in any way, you can do so using the OAM console as described in "Configuring and Managing Registered OAM Agents Using the Console" in Administrator's Guide for Oracle Access Management.

The MSAS instance will be listed, using the instance name, on the WebGates tab of the Search SSO Agents page. You may need to click Search to display the list of WebGates.