Android

private AuthorizationAgent mAuthorization; 
private MobileBackend mobileBackend; 

try {
  mobileBackend = MobileBackendManager.getManager().getMobileBackend(this);
} catch (ServiceProxyException e) {
      e.printStackTrace();
}

mAuthorization = mobileBackend.getAuthorization(AuthType.TOKENAUTH);

iOS

-(void) authenticateSSOTokenExchange: (NSString*) token
                    storeAccessToken:(BOOL) storeToken
                     completionBlock: (OMCErrorCompletionBlock) completionBlock;

Cordova and JavaScript

mcs.mobileBackend.setAuthenticationType(mcs.AUTHENTICATION_TYPES.token);
mcs.mobileBackend.authorization.authenticate(token).then(callback).catch(errorCallback);

Root Fields

• issuers — Required. A JSON array of trusted issuers objects. Each trusted issuer is defined as a JSON object, with a combination of the following fields.

• policyMinReloadInterval — Optional. If a token exchange request is received, and the specified issuer is not found in the configuration cache, the configuration cache will automatically be reloaded from the stored policy in order to check for changes, unless the amount of time since the last configuration cache reload is less than the policyMinReloadInterval. The default value for this interval is 10 seconds. The policyMinReloadInterval configuration field can be used to override the default value with a specified integer value in seconds.

• policyMaxReloadInterval — Optional. If a token exchange request is received, if the elapsed time since the last time the configuration cache was reloaded is in excess of policyMaxReloadInterval, the configuration cache will automatically be reloaded from the stored policy in order to check for changes. The default value for this interval is 120 seconds. The policyMaxReloadInterval configuration field can be used to override the default value with a specified integer value in seconds.

• certificatesMinReloadInterval — Optional. If a token exchange request is received, and a required certificate is not found in the certificates cache, the certificates cache will automatically be reloaded from Oracle Keystore Service (KSS) in order to check for changes, unless the amount of time since the last certificates cache reload is less than the certificatesMinReloadInterval. The default value for this interval is 10 seconds. The certificatesMinReloadInterval configuration field can be used to override the default value with a specified integer value in seconds.

• certificatesMaxReloadInterval — Optional. If a token exchange request is received, if the elapsed time since the last time the certificates cache was reloaded is in excess of certificatesMaxReloadInterval, the certificates cache will automatically be reloaded from KSS in order to check for changes. The default value for this interval is 300 seconds. The certificatesMaxReloadInterval configuration field can be used to override the default value with a specified integer value in seconds.

Issuer Fields

• issuerName — Required. A JSON string which specifies the issuer name. This value must match the value of the iss claim in tokens from the associated token issuer.

• enabled — Optional. A JSON boolean which can be used to enable or disable the token issuer. If the token issuer is disabled, any attempt to exchange a token from that issuer will fail. The default value is true.

• audience — Optional. A JSON array of string values, specifying valid audience values for the external token. If the external token contains an aud claim and none of the associated values exactly matches one of the values in the specified list, then the external token will be treated as invalid.

  The default behavior if this field is not specified (or contains an empty list) is to compare the aud values in the external token to the following values:

  • base-URL

  • base-URL/

  • base-URL/mobile

  • base-URL/mobile/

  • base-URL/mobile/platform

  • base-URL/mobile/platform/

  • base-URL/mobile/platform/auth

  • base-URL/mobile/platform/auth/

  • base-URL/mobile/platform/auth/token

  • base-URL/mobile/platform/auth/token/

  If none of the aud values in the external token match any of the above values, the external token will be treated as invalid.

• virtualUserEnabled — Optional. If true the virtual user (zero footprint) feature is enabled for this issuer, meaning your users can authenticate with third-party tokens without having corresponding user accounts in Oracle Cloud. The default value is false.

• usernameAttribute — Optional. A JSON string specifying the name of a JWT token claim from which a username is extracted. If no value is provided, the value of the sub claim will be used as the username.

• requireClientAuth — Optional. A JSON boolean which can be used to configure whether client authentication is required for this token issuer.

  • If the value is true, full client authentication is required.

  • If the value is false, a token exchange request can contain a client-id value in the POST body, with no client_secret value provided. This is intended only for cases where devices are not able to protect the client_secret.

  The default value is true.

• clientIdAttribute — Optional. A JSON string specifying the name of a JWT token claim which contains the client ID of the OAuth client on the external token issuer which was used to obtain the external token. If a clientIdAttribute value is specified, the specified attribute is present in a token, and its value matches the username associated with the token, then the token exchange request will be rejected, because client tokens shouldn’t be exchanged for MCS user tokens.

  If no clientIdAttribute value is provided, this check will not be performed.

• tokenTimeoutSeconds — Optional. A JSON integer specifying the token lifetime (i.e. from iat to exp) in seconds for MCS tokens issued in exchange for tokens from this issuer. If this field is not specified, the token lifetime will be governed by the Security_TokenExchangeTimeoutSecs policy. If the Security_TokenExchangeTimeoutSecs policy has not been defined, the default token lifetime is 28800 seconds (i.e. 8 hours).

  The token lifetime is also governed by the tokenTimeoutPolicy.

• tokenTimeoutPolicy — Optional. A JSON string specifying the policy used to control the token lifetime (i.e. from iat to exp) for MCS tokens issued in exchange for tokens from this issuer. Three policy values are supported:

  • FromTimeoutSecs — The token lifetime is governed by the tokenTimeoutSeconds value.

  • FromExternalToken — The MCS-issued token will expire at the same time the external token being exchanged will expire (i.e. tokenTimeoutSeconds is ignored).

  • FromExternalTokenLimitedByTimeoutSecs — The MCS-issued token will expire at the same time the external token being exchanged or after the token timeout value, whichever comes first.

  If this field is not specified, the token timeout policy lifetime will be governed by the Security_TokenExchangeTimeoutPolicy policy. If the Security_TokenExchangeTimeoutPolicy policy has not been defined, the default token timeout policy is FromTimeoutSecs.

• jwks— Optional. A JSON object which specifies the URI(s) and other configuration options associated with loading keys and/or certificates from the external token issuer on the fly.

  Use this object if you are using a discovery URI to load keys and/or certificates (and you are not using a certificateSubjectNames object).

  See jwks Fields for the options.

• certificateSubjectNames — Optional. A JSON array of strings containing a list of the certificate subject names of certificates that have been uploaded into MCS through the Administration tab’s Keys and Certificates page. (See Configuring a Web Service or Token Certificate.)

  Use this object if you are not using a discovery URI to load keys and/or certificates (and therefore are not using a jwks object).

• filters — Optional. A JSON array of filter objects. Each filter is defined as a JSON object, with a combination of these fields:

  • name — Required. A JSON string specifying the name of an attribute or claim to which the filter will be applied.

  • type — Optional. A JSON string specifying whether the filter is an include filter or an exclude filter.

    An include filter is satisfied if the token contains a value which matches one or more of the specified filter values (i.e. presence of a "match" causes the filter to be satisfied). An exclude filter is satisfied if the token does not contains a value which matches any of the specified filter values (i.e. absence of a "match" causes the filter to be satisfied).

    The default value is include.

  • values — Required. A JSON array of string values which will be compared to the value of the attribute or claim in the external token as identified by the name field.

    Filter values may contain the * character as a wildcard for matching purposes.

  Each filter in the array must be satisfied in order for the external token to be considered valid.

  Note:

  If a filter is specified incorrectly or incompletely (e.g. missing name, invalid type, missing or empty values array) the filter will always be considered to be not satisfied. The rationale is that the admin who configured the filter was trying to filter out something, and if we cannot figure out what that something is, it is better to err on the side of caution, and reject the external token.

• allowedMbes — Optional. A JSON array of JSON objects which identify mobile backends can be used with this token issuer.

  You can specify a mobile backend including the name and version, or by including just clientId.

  If this field isn’t specified, the issuer can be used with any mobile backend.

  Here are the possible entries:

  • name — Optional. A JSON string specifying the name of a mobile backend. If you include this field, you must also include version.

  • version — Optional. A JSON string specifying the mobile backend version. If you include this field, you must also include name.

  • clientId — Optional. A JSON string specifying the OAuth client ID of a mobile backend.

• userMappingAttribute — Optional. A JSON string identifying the user attribute used to search for an Oracle Cloud user to be associated with the token exchange.

  This attribute is ignored if virtualUserEnabled is set to true.

  The string can have one of the following values:

  • uid — Search for an Oracle Cloud user whose username matches the username extracted from the external token.

  • mail — Search for an Oracle Cloud user whose email address matches the username extracted from the external token.

  The default value is uid.

  Note:

  If a usernameAttribute hasn’t been configured, the username extracted from the external token will be the value of the sub claim. If a usernameAttribute has been configured, the username extracted from the external token will be the value of the whatever claim is identified by the usernameAttribute value.

• defaultRoles — Optional. A JSON array of strings, where each string is the name of an MCS role which should be granted to a virtual user in the case where no roleAttributes value has been configured or where a roleAttributes value is configured but the specified attributes are either absent from the external token or are empty. 

• issuerRoles — Optional. A JSON array of strings, where each string is the name of an MCS role which should be always granted to a virtual user when a token from this external issuer is exchanged. The difference between default roles and issuer roles is that default roles are granted only when no roles have been found during processing of role attributes, while issuer roles are always granted.

• roleAttributes — Optional. A JSON array of strings where each string is the name of a token attribute (i.e. claim) which should be searched for role values. If a specified token attribute is not present in the external token, no roles will be added for that attribute. Otherwise, the token attribute value will be processed as follows:

  • If the token attribute value contains a JSON string, the string value will be granted as a role, subject to role mapping (see theroleMappings field).

  • If the token attribute value contains a JSON array of JSON string values, each of the string values will be granted as a role, subject to role mapping.

  If no roleAttributes array is provided, the external token will not be searched for roles, and the roles to be granted to the user will be based on defaultRoles and/or issuerRoles configuration, where provided.

• roleMappings — Optional. A JSON array of role mapping objects, each of which specifies a mapping from a token role value (i.e. a value obtained from roleAttributes) and one or more MCS roles. Use this field when the values derived from role attributes do not match MCS role names.

  Here are the fields for a role mapping object:

  • tokenRole — Required. A JSON string specifying a token role name.

  • mappedRoles — Required. A JSON array of string values. Each string value should match an MCS role name.

  .

jwks Fields

• discoveryUri — Optional. A JSON string specifying the URI from which the token issuer's discovery information can be loaded. The discovery information provided by the external token issuer must be in accordance with the following specification:

  http://openid.net/specs/openid-connect-discovery-1_0.html

  The discovery URI for a token issuer will typically be of the form base-url/.well-known/openid-configuration, but MCS does not require this to be the case.

  If a discoveryUri is configured for a token issuer, the MCS token exchange service will make a GET request to that URL to obtain the discovery information as needed. Once the discovery information has been obtained, MCS will typically use the jwks_uri value specified in the discovery information to obtain the issuer's current keys and/or certificates.

  If no discoveryUri is configured, then a jwksUri value must be configured.

• jwksUri — Optional. A JSON string specifying the URI from which the token issuer's JWKS information can be loaded. The information provided by the external token issuer must be in accordance with the following specification:   

  https://tools.ietf.org/html/rfc7517

  If a jwksUri is configured for a token issuer, the MCS token exchange service will make a GET request to that URL to obtain the current keys and/or certificates for that issuer as needed.

  If both a discoveryUri and a jwksUri are specified in the configuration, the configured jwksUri value will be used, overriding the value in the issuer's discovery information.

• allowHttp — Optional. A JSON boolean indicating that HTTP discoveryUri and jwksUri values should be allowed.

  For security reasons, discoveryUri and jwksUri values for external token issuers in production should always use HTTPS URLs, so that the server providing the information can be verified using its SSL certificate. However, in certain non-production test scenarios, it may be helpful to allow HTTP URIs to be used.

  The default value is false.

• minReloadInterval — Optional. If a token exchange request is received, and the key and/or certificate needed to validate the external token cannot be found, MCS will automatically reload the discovery and JWKS information in order to check for changes (e.g. key rotation), unless the amount of time since the discovery/JWKS reload is less than this value (in seconds, expressed as an integer).

  The default value is 60.

• maxReloadInterval — Optional. If a token exchange request is received and if the elapsed time since the last time the discovery and JWKS information was reloaded is in excess of this value (in seconds, expressed as an integer), the discovery and JWKS information will automatically be reloaded from the external token issuer in order to check for changes.

  The default value is 28800 (i.e. 8 hours).

• connectTimeout — Optional. A JSON integer specifying the default connect timeout for discovery and/or JWKS requests. The default is 30 seconds.

• readTimeout — Optional. A JSON integer specifying the default read timeout for discovery and/or JWKS requests. The default is 60 seconds

• tlsVersions — Optional. A JSON array of string values, listing the SSL/TLS which will be allowed when connecting to the external token issuer for Discovery and/or JWKS requests. Valid version names are:

  • SSL

  • SSLv2

  • SSLv3

  • TLS

  • TLSv1

  • TLSv1.1

  • TLSv1.2

  The default value is ["TLSv1.1", "TLSv1.2"].

  Note:

  Older SSL/TLS versions are considered insecure, and should be avoided.

• authorizationHeader — Optional. A JSON string specifying an Authorization header value which should be included in discovery and/or JWKS requests. In most cases, discovery and JWKS web pages are public and no authorization is required. This property is intended primarily for test purposes (e.g. when setting up a custom service to act as a discovery and/or JWKS endpoint).

Android

private AuthorizationAgent mAuthorization; 
private MobileBackend mobileBackend; 

try {
  mobileBackend = MobileBackendManager.getManager().getMobileBackend(this);
} catch (ServiceProxyException e) {
      e.printStackTrace();
}

mAuthorization = mobileBackend.getAuthorization(AuthType.TOKENAUTH);

iOS

-(void) authenticateSSOTokenExchange: (NSString*) token
                    storeAccessToken:(BOOL) storeToken
                     completionBlock: (OMCErrorCompletionBlock) completionBlock;

Cordova and JavaScript

mcs.mobileBackend.setAuthenticationType(mcs.AUTHENTICATION_TYPES.token);
mcs.mobileBackend.authorization.authenticate(token).then(callback).catch(errorCallback);