Using the Authenticate API to Develop a Custom Sign-in Page

Step 1: Begin the Authentication Flow 🔗

A user opens a browser window to access a protected page.

Example HTML Form POST

The following is an example HTML Form POST that identity domains returns to invoke the custom sign-in page:

<form name="autosubmit" id="autosubmit" action="<custom_ui_signin_URL>" method="POST" onload="submitform();">
     <input name="loginCtx" value="<obfuscated_loginctx_value>" />
     <input name="signature" value="signature_data" />
</form>

Example Decryption Logic for Encrypted loginCtx in Java

The following is example decryption logic:

public static String decrypt(String tenantName, String attrName, String attrDecryptValue ) {
        String attrDecrypt = attrDecryptValue;
        final String SHA_256_ALG = "SHA-256";
        final String ENCRYPTION_ALG = "AES/CBC/PKCS5Padding";
        final String SECRET_KEY_ALG = "AES";
        String data = null;
        MessageDigest md = null;
        byte[] keyBytes = new byte[16];
        try {
            md = JCECryptoCache.getMessageDigestInstance(SHA_256_ALG);
            byte[] digest = md.digest(tenantName.toLowerCase().getBytes("UTF-8"));
            System.arraycopy(digest, 0, keyBytes, 0, 16);
        } catch (Exception ex) {
            ex.printStackTrace();
        } finally {
            JCECryptoCache.releaseMessageDigestInstance(md);
        }
 
        // encrypt the data
        Cipher decipher = null;
        try {
            decipher = JCECryptoCache.getCipherInstance(ENCRYPTION_ALG);
            SecretKey secretKey = new SecretKeySpec(keyBytes, SECRET_KEY_ALG);
            decipher.init(Cipher.DECRYPT_MODE,
                    secretKey, new IvParameterSpec(new byte[16]));
            byte[] decryptedData = decipher.doFinal(Base64.getDecoder().decode(attrDecrypt.getBytes("UTF-8")));
            data = new String(decryptedData);
            System.out.println("" + data);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        return data;
    }

Response Example

The response should be similar to the following example:

{
  "requestState": "TasNtIxDqWOfDKeTM",
  "nextOp": [
    "credSubmit",
    "chooseIDP"
  ],
  "nextAuthFactors": [
    "IDP",
    "USERNAME_PASSWORD"
  ],
  "status": "success",
  "ecId": "GmY95180000000000",
  "USERNAME_PASSWORD": {
    "credentials": [
      "username",
      "password"
    ]
  },
  "IDP": {
    "configuredIDPs": [
      {
        "iconUrl": "null",
        "idpName": "adc00peq",
        "idpType": "Saml"
      },
      {
        "idpId": "4bb89888feea4b00a0fab3a1a5627539",
        "idpName": "Google",
        "idpType": "Social"
      }
    ],
    "credentials": [
      "idpId",
      "idpType"
    ]
  }
}

The values of these attributes define which authentication factor, identity providers, and social providers are presented on the sign-in page. The sign-in page appears containing the decrypted values of the loginCtx parameter along with the access token. The sign-in page includes JavaScript that's used to perform AJAX calls to identity domains.

Step 2: Select a SAML Identity Provider 🔗

Example HTML Form POST Code to Select a SAML IdP

var addParamValues = function(myform, value, paramName) {
    if (value !== null && value !== 'undefined') {
        param = document.createElement("input");
        param.value = value;
        param.name = paramName;
        myform.appendChild(param);
    }
};
 
var chooseRemoteIDP = function(name, idpId, type) {
    var myform = document.createElement("form");
    myform.action = GlobalConfig.idcsBaseURL + "/sso/v1/sdk/secure/idp";
    myform.method = "post";
    <%
        Credentials creds = CredentialsList.getCredentials().get(attr);
        String clientId = creds.getId();
    %>
    var clientId = '<%=clientId%>';
    addParamValues(myform, name, "idpName");
    addParamValues(myform, type, "idpType");
    addParamValues(myform, idpId, "idpId");
    addParamValues(myform, clientId, "clientId");
    addParamValues(myform, authorization, "accesstoken")
    addParamValues(myform, GlobalConfig.requestState, "requestState");
    document.body.appendChild(myform);
    myform.submit();
};
 
var activateIdp = function(name, idpId) {
    chooseRemoteIDP(name, idpId, "SAML");
};
 
var activateSocialIdp = function(name, idpId) {         
    chooseRemoteIDP(name, idpId, "SOCIAL");
};

Request Example

The following is an example of the contents of the FORM POST to the /sso/v1/sdk/secure/idp endpoint:

requestState=value&idpName=value&idpType=SAML&idpId=value&appName=name&clientID=value&authorization=accesstoken

Response Example

The following example shows the contents of the response in standard HTTP format:

HTTP/1.1 302 See Other
Date: Tue, 30 Oct 2018 04:40:05 GMT
Content-Length: 0
Connection: keep-alive
Pragma: no-cache
Location: https://<domainURL>/idp/sso (Example URL)
Set-cookie: ORA_OCIS_REQ_1=+fxgW2P7bgQayiki5P;Version=1;Path=/;Secure;HttpOnly
Expires: Sat, 01 Jan 2000 00:00:00 GMT
X-xss-protection: 1; mode=block
X-content-type-options: nosniff

Identity domains processes the request and redirects the browser to the selected external IdP for authentication and authorization. When the external IdP is finished, the browser is redirected to identity domains. Identity domains validates the assertion response and checks if additional authentication such as MFA is required.

If additional authentication isn't required, then identity domains creates the session and redirects the browser to the target URL. Or, identity domains creates an HTML auto submit FORM POST to the custom sign-in page that contains the authnToken. The custom sign-in page then creates the session. See Creating a Session.

Step 1: Begin the Authentication Flow 🔗

A user opens a browser window to access a protected page.

Example HTML Form POST

The following is an example HTML Form POST that identity domains returns to invoke the custom sign-in page:

<form name="autosubmit" id="autosubmit" action="<custom_ui_signin_URL>" method="POST" onload="submitform();">
     <input name="loginCtx" value="<obfuscated_loginctx_value>" />
     <input name="signature" value="signature_data" />
</form>

Example Decryption Logic for Encrypted loginCtx in Java

The following is example decryption logic:

public static String decrypt(String tenantName, String attrName, String attrDecryptValue ) {
        String attrDecrypt = attrDecryptValue;
        final String SHA_256_ALG = "SHA-256";
        final String ENCRYPTION_ALG = "AES/CBC/PKCS5Padding";
        final String SECRET_KEY_ALG = "AES";
        String data = null;
        MessageDigest md = null;
        byte[] keyBytes = new byte[16];
        try {
            md = JCECryptoCache.getMessageDigestInstance(SHA_256_ALG);
            byte[] digest = md.digest(tenantName.toLowerCase().getBytes("UTF-8"));
            System.arraycopy(digest, 0, keyBytes, 0, 16);
        } catch (Exception ex) {
            ex.printStackTrace();
        } finally {
            JCECryptoCache.releaseMessageDigestInstance(md);
        }
 
        // encrypt the data
        Cipher decipher = null;
        try {
            decipher = JCECryptoCache.getCipherInstance(ENCRYPTION_ALG);
            SecretKey secretKey = new SecretKeySpec(keyBytes, SECRET_KEY_ALG);
            decipher.init(Cipher.DECRYPT_MODE,
                    secretKey, new IvParameterSpec(new byte[16]));
            byte[] decryptedData = decipher.doFinal(Base64.getDecoder().decode(attrDecrypt.getBytes("UTF-8")));
            data = new String(decryptedData);
            System.out.println("" + data);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        return data;
    }

Response Example

The response should be similar to the following example:

{
  "requestState": "TasNtIxDqWOfDKeTM",
  "nextOp": [
    "credSubmit",
    "chooseIDP"
  ],
  "nextAuthFactors": [
    "IDP",
    "USERNAME_PASSWORD"
  ],
  "status": "success",
  "ecId": "GmY95180000000000",
  "USERNAME_PASSWORD": {
    "credentials": [
      "username",
      "password"
    ]
  },
  "IDP": {
    "configuredIDPs": [
      {
        "iconUrl": "null",
        "idpName": "adc00peq",
        "idpType": "Saml"
      },
      {
        "idpId": "4bb89888feea4b00a0fab3a1a5627539",
        "idpName": "Google",
        "idpType": "Social"
      }
    ],
    "credentials": [
      "idpId",
      "idpType"
    ]
  }
}

The values of these attributes define which authentication factor, identity providers, and social providers are presented on the sign-in page. The sign-in page appears containing the decrypted values of the loginCtx parameter along with the access token. The sign-in page includes JavaScript that's used to perform AJAX calls to identity domains.

Step 2: Select a Social Identity Provider 🔗

Example HTML Form POST Code to Select a Social IdP

var addParamValues = function(myform, value, paramName) {
    if (value !== null && value !== 'undefined') {
        param = document.createElement("input");
        param.value = value;
        param.name = paramName;
        myform.appendChild(param);
    }
};
 
var chooseRemoteIDP = function(name, idpId, type) {
    var myform = document.createElement("form");
    myform.action = GlobalConfig.idcsBaseURL + "/sso/v1/sdk/secure/idp";
    myform.method = "post";
    <%
        Credentials creds = CredentialsList.getCredentials().get(attr);
        String clientId = creds.getId();
    %>
    var clientId = '<%=clientId%>';
    addParamValues(myform, name, "idpName");
    addParamValues(myform, type, "idpType");
    addParamValues(myform, idpId, "idpId");
    addParamValues(myform, clientId, "clientId");
    addParamValues(myform, authorization, "accesstoken")
    addParamValues(myform, GlobalConfig.requestState, "requestState");
    document.body.appendChild(myform);
    myform.submit();
};
 
var activateIdp = function(name, idpId) {
    chooseRemoteIDP(name, idpId, "SAML");
};
 
var activateSocialIdp = function(name, idpId) {         
    chooseRemoteIDP(name, idpId, "SOCIAL");
};

Request Example

The following is an example of the contents of the FORM POST to the /sso/v1/sdk/secure/idp endpoint:

requestState=value&idpName=value&idpType=Social&idpId=value&appName=name&clientID=value&authorization=accesstoken

Response Example

The following example shows the contents of the response in JSON format:

HTTP/1.1 302 See Other
Date: Tue, 30 Oct 2018 04:40:05 GMT
Content-Length: 0
Connection: keep-alive
Pragma: no-cache
Location: https://<domainURL>/idp/sso (Example URL)
Set-cookie: ORA_OCIS_REQ_1=+fxgW2P7bgQayiki5P;Version=1;Path=/;Secure;HttpOnly
Expires: Sat, 01 Jan 2000 00:00:00 GMT
X-xss-protection: 1; mode=block
X-content-type-options: nosniff

Identity domains processes the request and redirects the browser to the selected social IdP for authentication and authorization. When the social IdP is finished, the browser is redirected to identity domains. Identity domains validates the assertion response and checks if additional authentication such as MFA is required.

If additional authentication isn't required, then identity domains creates the session and redirects the browser to the target URL. Or, identity domains creates an HTML auto submit FORM POST to the custom sign-in page that contains the authnToken. The custom sign-in page then creates the session. See Creating a Session.

Step 1: Begin the Authentication Flow 🔗

A user opens a browser window to access a protected page.

Example HTML Form POST

The following is an example HTML Form POST that identity domains returns to invoke the custom sign-in page:

<form name="autosubmit" id="autosubmit" action="<custom_ui_signin_URL>" method="POST" onload="submitform();">
     <input name="loginCtx" value="<obfuscated_loginctx_value>" />
     <input name="signature" value="signature_data" />
</form>

Example Decryption Logic for Encrypted loginCtx in Java

The following is example decryption logic:

public static String decrypt(String tenantName, String attrName, String attrDecryptValue)
        {       
            String attrDecrypt = attrDecryptValue;        
            final String SHA_256_ALG = "SHA-256";       
            final String ENCRYPTION_ALG = "AES/CBC/PKCS5Padding";        
            final String SECRET_KEY_ALG = "AES";       
            String data = null;       
            MessageDigest md = null;       
            byte[] keyBytes = new byte[16];       
            try {           
                md = MessageDigest.getInstance(SHA_256_ALG);           
                byte[] digest = md.digest(tenantName.toLowerCase().getBytes("UTF-8"));           
                System.arraycopy(digest, 0, keyBytes, 0, 16);      
            } catch (Exception ex) 
            {           
              ex.printStackTrace();       
            }          
        // encrypt the data       
        Cipher decipher = null;       
        try {           
        decipher = Cipher.getInstance(ENCRYPTION_ALG);           
        SecretKey secretKey = new SecretKeySpec(keyBytes, SECRET_KEY_ALG);           
        decipher.init(Cipher.DECRYPT_MODE,           
        secretKey, new IvParameterSpec(new byte[16]));           
        byte[] decryptedData = decipher.doFinal(Base64.getDecoder().decode(attrDecrypt.getBytes("UTF-8")));           
        data = new String(decryptedData);           
        System.out.println("" + data);        }
        catch (Exception ex)
        {           
        ex.printStackTrace();       
        }       
        return data;   
       }

Response Example

The response should be similar to the following example:

{
  "requestState": "TasNtIxDqWOfDKeTM",
  "nextOp": [
    "credSubmit",
    "chooseIDP"
  ],
  "nextAuthFactors": [
    "IDP",
    "USERNAME_PASSWORD"
  ],
  "status": "success",
  "ecId": "GmY95180000000000",
  "USERNAME_PASSWORD": {
    "credentials": [
      "username",
      "password"
    ]
  },
  "IDP": {
    "configuredIDPs": [
      {
        "iconUrl": "null",
        "idpName": "adc00peq",
        "idpType": "Saml"
      },
      {
        "idpId": "4bb89888feea4b00a0fab3a1a5627539",
        "idpName": "Google",
        "idpType": "Social"
      }
    ],
    "credentials": [
      "idpId",
      "idpType"
    ]
  }
}

The values of these attributes define which authentication factor, identity providers, and social providers are presented on the sign-in page. The sign-in page appears containing the decrypted values of the loginCtx parameter along with the access token. The sign-in page includes JavaScript that's used to perform AJAX calls to identity domains.

Step 2: Select an External Identity Provider 🔗

Example HTML Form POST Code to Select an External IdP

var addParamValues = function(myform, value, paramName) {
    if (value !== null && value !== 'undefined') {
        param = document.createElement("input");
        param.value = value;
        param.name = paramName;
        myform.appendChild(param);
    }
};
 
var chooseRemoteIDP = function(name, idpId, type) {
    var myform = document.createElement("form");
    myform.action = GlobalConfig.idcsBaseURL + "/sso/v1/sdk/secure/idp";
    myform.method = "post";
    <%
        Credentials creds = CredentialsList.getCredentials().get(attr);
        String clientId = creds.getId();
    %>
    var clientId = '<%=clientId%>';
    addParamValues(myform, name, "idpName");
    addParamValues(myform, type, "idpType");
    addParamValues(myform, idpId, "idpId");
    addParamValues(myform, clientId, "clientId");
    addParamValues(myform, authorization, "accesstoken") 
    addParamValues(myform, GlobalConfig.requestState, "requestState");
    document.body.appendChild(myform);
    myform.submit();
};
 
var activateIdp = function(name, idpId) {
    chooseRemoteIDP(name, idpId, "SAML");
};
 
var activateSocialIdp = function(name, idpId) {         
    chooseRemoteIDP(name, idpId, "SOCIAL");
};

Request Example

The following is an example of the contents of the FORM POST to the /sso/v1/sdk/secure/idp endpoint:

requestState=value&idpName=value&idpType=SAML&idpId=value&appName=name&clientID=value&authorization=accesstoken

Response Example

The following example shows the contents of the response in standard HTTP format:

HTTP/1.1 302 See Other
Date: Tue, 30 Oct 2018 04:40:05 GMT
Content-Length: 0
Connection: keep-alive
Pragma: no-cache
Location: https://<domainURL>/idp/sso (Example URL)
Set-cookie: ORA_OCIS_REQ_1=+fxgW2P7bgQayiki5P;Version=1;Path=/;Secure;HttpOnly
Expires: Sat, 01 Jan 2000 00:00:00 GMT
X-xss-protection: 1; mode=block
X-content-type-options: nosniff

Identity domains processes the request and redirects the browser to the selected external IdP for authentication and authorization. When the external IdP is finished, it redirects the browser to identity domains, which then redirects the browser to begin 2-Step Verification.

Step 3: Authenticate Using the Preferred Factor (SMS) 🔗

The initial steps to begin 2-Step Verification are similar to Step 1. Identity domains creates and submits an HTML form that contains the encrypted loginCtx and signature parameters. See Step 1 for detailed information on the form POST and how to decrypt.

After the loginCtx parameter is decrypted, the response should be similar to the following example:

{
    "status": "success",
    "displayName": "Joe's iPhone",
    "nextAuthFactors": [
        "SMS"
    ],
    "SMS": {
        "credentials": [
            "otpCode"
        ]
    },
    "nextOp": [
        "credSubmit",
        "getBackupFactors",
        "resendCode"
    ],
    "requestState": "QjyV3ueFrGQCO.....84gQw2UUm2V7s",
    "trustedDeviceSettings": {
        "trustDurationInDays": 15
    }
}

The values of these attributes define which authentication factor (in this example it is SMS) to present on the sign-in page. The user enters the one-time passcode that they receive on their device.

Request Example

The following example shows the contents of the POST request in JSON format to complete authentication using the preferred method:

{  
   "op":"credSubmit",
     "credentials":{  
      "otpCode":"108685"
   },
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "authnToken": "eyJraWQiOiJT.....kLbxxL97U_0Q",
    "status": "success"
}

A session must then be created. After the session is created, the browser is redirected to the originally requested URL. See Creating a Session.

Step 1: Begin the Authentication Flow 🔗

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format:

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

In the response, the nextOp value indicates what can be sent as the op value in the next request. In this use case example, credSubmit should be sent in the next step. The requestState contains contextual data needed to process the request.

Step 2: Submit the User's Credentials 🔗

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "authnToken": "eyJraWQiOiJT.....UKofudtemmJE",
    "status": "success"
}

Error Response Example

The following example shows the contents of the response in JSON format when the user name or password provided is invalid:

{
    "status": "failed",
    "cause": [
        {
            "message": "You entered an incorrect username or password.",
            "code": "AUTH-3001"
        }
    ],
    "requestState": "e5kwGYx57taQ.....jyg3nEDFya"
}

Step 1: Begin the Authentication Flow 🔗

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format:

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

In the response, the nextOp value indicates what can be sent as the op value in the next request. In this use case example, credSubmit should be sent in the next step. The requestState contains contextual data needed to process the request.

Step 2: Submit the User's Credentials Without MFA) 🔗

If the username and passwords are valid, the server responds with the TOU statement in the locale specified in the user's profile. The server also prompts the user to provide their consent credential in the next request. If the TOU statement isn't present in the user's locale fr, then 401 response with the error message AUTH-3036 : Terms of Use Statement for locale fr isn't added is displayed.

Request Example

The following example shows the contents of the POST request in JSON format to the /sso/v1/sdk/authenticate endpoint:

{  
   "op":"credSubmit",
   "credentials":{  
      "username":"{{username}}",
      "password":"{{password}}"
   },
   "requestState":"{{requestState}}"
}
}

Response Example

The following example shows the contents of the response in JSON format when the user's locale is added:

{
  "nextOp": [
   "acceptTOU"
  ],
  "TOU": {
    "statement": "This is a placeholder text. Customers must provide the actual Terms of Use.",
    "credentials": [
    "consent"
    ],
    "locale": "en"
  },
 "requestState": "q/tRS4BFAdaimSBhq"
}
}

Error Response Example

The following example shows the contents of the response in JSON format when the TOU for user's locale isn't added:

{
    "status": "failed",
    "ecId": "Q0ApB1Y1000000000",
    "cause": [
        {
            "message": "Terms of Use Statement for locale fr isn't added.",
            "code": "AUTH-3036"
        }
    ]
}
}

Step 3: Provide the TOU Consent 🔗

In this scenario, the user either accepts or rejects the Terms of Use for the application. If user agrees to Terms of Use, then the user is redirected to the application page.

If user rejects the Terms of Use, then 401 response with error message, AUTH-3035 : You must accept the Terms of Use to access this application, is displayed.

Request Example

The following example shows the contents of the request in JSON format when the user agrees to TOU.

{
 "op": "acceptTOU",
 "credentials": {
   "consent": true
 },
 "requestState": "{{requestState}}"
}

Request Example

The following example shows the contents of the request in JSON format when the user rejects the TOU.

{
 "op": "acceptTOU",
 "credentials": {
   "consent": false
 },
 "requestState": "{{requestState}}"
}

Response Example

The following example shows the content of the response in JSON format when the user agrees to TOU statement.

{
    "authnToken": "eyJ4NXQjUzI1NiI6Iks0R0hvZVdoUm...YUAvuEOrERXrQRnjybdOkA2Q",
    "status": "success",
    "ecId": "Q0ApB1Y1000000000"
}

Error Response Example

The following shows the contents of the response in JSON format when the TOU is rejected by the user.

{
    "status": "failed",
    "ecId": "Q0ApB1Y1000000000",
    "cause": [
        {
            "message": "You must accept the Terms of Use to access this application.",
            "code": "AUTH-3035"
        }
    ]
}

Identity domains can be configured to send a time-based one-time passcode (OTP) to directly to a user for authentication or have the passcode encrypted and sent to the consuming client who can then send it to the user for authentication.

For example, administrators can configure identity domains to send time-based one-time passcodes (OTP) to the Oracle Mobile Authenticator (OMA) app or email the OTPs to the user's primary email address. In both cases, identity domains generate the OTP, sends it directly to the user and the user enters the code for authentication. To understand how to set these options using REST, see Authentication Factor Enrollment With Factor Verification-SMS and Authentication Factor Enrollment With Factor Verification-Email.

Encryption and Decryption

This implementation uses the following specification to encrypt and decrypt the OTP code received. See PKCS #1: RSA Cryptography Specifications, Version 2.0, section 7.1 RSAES-OAEP.

OTP Decryption Code

/*
 * To change this license header, choose License Headers in Project Properties.
 * To change this template file, choose Tools | Templates
 * and open the template in the editor.
 */
package decryption;

import java.security.Key;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.cert.CertificateFactory;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import javax.crypto.Cipher;

/**
 *
 * @author <author>
 */
public class DecryptOtpCode {
    
    private static Key getPrivateKey(String privateKeyPEM) throws Exception {
        byte[] encoded = Base64.getDecoder().decode(privateKeyPEM);
        KeyFactory kf = KeyFactory.getInstance("RSA");
        PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(encoded);
        return kf.generatePrivate(keySpec);
    }
    
    public static void main(String args[]) {
        String value = "<encrypted_value>";
        String privatekey = 
                            "<pem_privatekey_data>";
        try {
                Cipher cipherInstance =
                        Cipher.getInstance("RSA/ECB/OAEPwithSHA1andMGF1Padding");
                CertificateFactory factory = CertificateFactory.getInstance("X.509");
                byte [] decoded = Base64.getDecoder().decode(value);
                PrivateKey pKey = (PrivateKey)getPrivateKey(privatekey);
                cipherInstance.init(Cipher.DECRYPT_MODE, pKey);
                byte[] decrypted = cipherInstance.doFinal(decoded);
                System.out.println("Decrypted text is " + new String(decrypted));
            } catch (Exception e) {
                //Unable to encrypt the content. Default to send the otp to user
                //no error or exception thrown.
                e.printStackTrace();
            }
    }
    
}

Step 1: Create a CustomUI Application 🔗

See Add Applications for more information about custom applications.

Step 2: Generate a Key Pair for a Self-Signed Certificate 🔗

Step 3: Configure the Application to Return the OTP in the Response 🔗

Step 4: Request the OTP 🔗

true

{
   "op": "credSubmit",
   "credentials": {
      "username": "test.user",
      "password": "example-password"
   },
   "userFlowControlledByExternalClient": true,
   "x5t": "<certificate thumbprint>",
   "requestState": "{{requestState}}"
}

"otp": {
        "value": "IMCw==",
        "alg": "RSAES-OAEP",
        "x5t": "<certificate thumbprint>"
 }

Response Example

{
    "otp": {
        "value": "IMsNO+rqNCw==",
        "alg": "RSAES-OAEP",
        "x5t": "<certificate thumbprint>"
    },
    "status": "success",
    "ecId": "Ft^OD161000000000",
    "displayName": "+91XXXXXXXX013",
    "nextAuthFactors": [
        "SMS"
    ],
    "SMS": {
        "credentials": [
            "otpCode"
        ]
    },
    "nextOp": [
        "credSubmit",
        "getBackupFactors",
        "resendCode"
    ],
    "scenario": "AUTHENTICATION",
    "requestState": "FrrACc",
    "trustedDeviceSettings": {
        "trustDurationInDays": 15
    }
}

Step 1: Begin the Authentication Flow 🔗

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format:

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

In the response, the nextOp value indicates what can be sent as the op value in the next request. In this use case example, credSubmit should be sent in the next step. The requestState contains contextual data needed to process the request.

Step 2: Submit the User's Credentials 🔗

AuthnToken is the id_token in JWT format that represents the current user information, session, and request data. This is used to create an SSO session cookie and redirect to the target URL. If the username and password are valid, the AuthnToken is retrieved.

Request Example

The following example shows the contents of the POST request in JSON format to the /sso/v1/sdk/authenticate endpoint:

{  
   "op":"credSubmit",
   "credentials":{  
      "username":"admin@oracle.com",
      "password":"example-password"
   },
   "requestState": "{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format where the AuthnToken is retrieved:

{
    "authnToken": "eyJ4NXQjUzI1NiI6Iks0R0hvZ...ZLjOZmKAvORB8OaV1Xqt1GL3tx1kyWA",
    "status": "success",
    "ecId": "5fR1O171000000000"
}

Step 3:Generate Access Token 🔗

After you retrieve an AuthnToken, it's used to get access token from OAuth server.

Request Example

The following example shows the contents of the request in JSON format:

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=urn:opc:idm:__myscopes__&assertion={{authnToken}}

Response Example

The following example shows the contents of the response in JSON format:

{
    "access_token": "<redacted>",
    "token_type": "Bearer",
    "expires_in": 7600
}

Step 4: Obtain User Information 🔗

The user submits the access token to obtain their information such as username, display name, email id, and so on.

Request Example

The following example shows the contents of the request in JSON format.

{{HOST}}/admin/v1/Me

Response Example

The following example shows the contents of the response in JSON format with user information.

{
    "idcsCreatedBy": {
        "type": "App",
        "display": "idcssm",
        "value": "4ba14c4be74d48d497da6ce651209a06",
        "$ref": "https://docteam.identity.internal.oracle.com:8943/admin/v1/Apps/4ba14c4be74d48d497da6ce651209a06"
    },
    "id": "de94e8399a0e4f23ac52fc681f5fb828",
    "meta": {
        "created": "2022-12-12T09:46:53.646Z",
        "lastModified": "2022-12-13T10:35:32.604Z",
        "resourceType": "Me",
        "location": "https://docteam.identity.internal.oracle.com:8943/admin/v1/Me/de94e8399a0e4f23ac52fc681f5fb828"
    },
    "active": true,
    "displayName": "admin opc",
    "idcsLastModifiedBy": {
        "value": "6567bac90beb4e65a2eb3b280b2f0d1f",
        "display": "idcssso",
        "type": "App",
        "$ref": "https://docteam.identity.internal.oracle.com:8943/admin/v1/Apps/6567bac90beb4e65a2eb3b280b2f0d1f"
    },
    "nickName": "TAS_TENANT_ADMIN_USER",
    "userName": "admin@oracle.com",
    "urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User": {
        "isFederatedUser": false
    },
    "emails": [
        {
            "verified": false,
            "primary": false,
            "secondary": false,
            "value": "admin@oracle.com",
            "type": "recovery"
        },
        {
            "verified": false,
            "primary": true,
            "secondary": false,
            "value": "admin@oracle.com",
            "type": "work"
        }
    ],
    "urn:ietf:params:scim:schemas:oracle:idcs:extension:userState:User": {
        "locked": {
            "on": false
        }
    },
    "name": {
        "formatted": "admin opc",
        "familyName": "opc",
        "givenName": "admin"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User",
        "urn:ietf:params:scim:schemas:oracle:idcs:extension:userState:User"
    ]
}

Step 1: Begin the Authentication Flow 🔗

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format:

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

In the response, the nextOp value indicates what can be sent as the op value in the next request. In this use case example, credSubmit should be sent in the next step. The requestState contains contextual data needed to process the request.

Step 2: Submit the User's Credentials 🔗

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format since PUSH Notifications is the preferred factor:

{
    "status": "pending",
    "displayName": "Joe's iPhone",
    "nextAuthFactors": [
        "PUSH"
    ],
    "cause": [
        {
            "code": "AUTH-1108",
            "message": "Push Notification approval is pending."
        }
    ],
    "nextOp": [
        "credSubmit",
        "getBackupFactors"
    ],
    "requestState": "rATagRibc//b.....xrKh7fJtIuWo",
    "trustedDeviceSettings": {
        "trustDurationInDays": 15
    }
}

"trustedDeviceSettings": {
       "trustDurationInDays": 0
 }

In the response, the status is pending since the user is required to Allow or Deny the PUSH Notification on their device. The nextOp values in the response indicate what can be sent as the op value in the next request. In this use case example, credSubmit is sent in the next step.

Step 3: Authenticate Using the Preferred Factor 🔗

Authenticate using the preferred factor, which in this use case example is PUSH Notifications. The client must include the following attributes in this request:

• op: tells the server what kind of operation the client wants

• requestState: received in the Step 2 response

Request Example

The following example shows the contents of the POST request in JSON format to complete authentication using the preferred method:

{  
   "op":"credSubmit",
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "authnToken": "eyJraWQiOiJT.....kLbxxL97U_0Q",
    "status": "success"
}

Step 1: Begin the Authentication Flow 🔗

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format:

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

In the response, the nextOp value indicates what can be sent as the op value in the next request. In this use case example, credSubmit should be sent in the next step. The requestState contains contextual data needed to process the request.

Step 2: Submit the User's Credentials 🔗

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "nextAuthFactors": [
        "TOTP",
        "SMS",
        "EMAIL",
        "SECURITY_QUESTIONS"
    ],
    "TOTP": {
        "credentials": [
            "offlineTotp"
        ]
    },
    "SMS": {
        "credentials": [
            "phoneNumber"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": false
    },
    "requestState": "m3oIaGVOlHwA...../Fi+1RpmKmd4"
}

In this use case example, since MFA is set as optional in the Sign-on Policy (indicated by a value of false for the enrollmentRequired attribute), the user is given a choice to either enroll or skip enrollment. If MFA is required, the only nextOp value would be enrollment.

In this use case example, enrollment is sent in the next step to initiate MFA factor enrollment for the user. Note that BYPASSCODE is missing as a nextAuthFactors value since the user can't enroll using a Bypass Code. The Bypass Code should be generated by the user using My Profile or by requesting that an administrator generate one for them.

Step 3: Initiate Second Factor Authentication Enrollment 🔗

Request Example

The following example shows the contents of the POST request in JSON format:

{  
   "op":"enrollment",
   "authFactor":"TOTP",
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "displayName": "Joe's Phone",
    "TOTP": {
        "credentials": [
            "otpCode"
        ],
        "qrCode": {
            "content": "oraclemobileauthenticator://totp/user?issuer=example1&Period=30&algorithm=SHA1&digits=6&RSA=SHA256withRSA&Deviceid=22f38324e67f4e2bb8e9e24583924a31&RequestId=9b428c1a-abb3-40ee-bd24-5064a87b638e&LoginURL=https%3A%2F%2Fexampletenant.com%3A8943%2Fsso%2Fv1%2F&OTP=eyJraWQiOiJTSUdOSU5HX0tFWSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJkZXZpY2VfaWQiOiIyMmYzODMyNGU2N2Y0ZTJiYjhlOWUyNDU4MzkyNGEzMSIsImlzcyI6IkF1dGhTcnYiLCJleHAiOjE1MjcxODEwODEsImlhdCI6MTUyNzE4MDc4MSwidGVuYW50IjoidGVuYW50MSJ9.Of0Hv5H3aRpDqdsiFLO0YkK2gbzq78k3jaJFwoWwR5LKOEH-9qTt1zjSiXujPD1T__8fEZDi8iKDyxXtL5zjAlEKd5wI026JjekG58ROPjW8gADWcMrTGQ4Lgw4Q0UPjk8Fm8AloQ1vS6xpDre6S-Vv620z28EKWZK_yGhUVSfAJVzSUxaypLtQhOQJBCNAzCElUgqyav7Vpi2z5eVQBQRtXv-Z_sTgrFXaVmVU3uSNVcg6zVX2x0fMQFgeO5lyC3U2Yy9JgA7iMfAMpuNvBzW0GjyByPAYRVnHSLPuHL1qiNx9ygpoVEcFLQJcOPuDLW2bW9ZwbUcVdS0F4L_2NfA&ServiceType=TOTP&KeyPairLength=2048&SSE=Base32",
            "imageType": "image/png",
            "imageData": "iVBORw0KG.......5ErkJggg=="
        }
    },
    "nextOp": [
        "credSubmit",
        "createToken",
        "createSession",
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": false
    },
    "requestState": "8A317/A1JiQe.....ce5/paoVOWw"
}

Step 4: Submit Factor Credentials 🔗

Request Example

The following example shows the contents of the POST request in JSON format to submit the factor credentials:

{  
   "op":"credSubmit",
   "requestState":"{{requestState}}"
}

Response Example

The success status appears in the response when the OMA app to server back-channel communication is completed and the optCode verification is successful. The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "displayName": "Joe's iPhone",
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "eyZa+10USFR7.....6I2vnfK82hnQ"
}

In the response, the nextOp values indicate what can be sent as the op value in the next request. In this use case example, createToken is sent in the next step.

Pending Response Example

The pending status appears when the OMA app to server back-channel communication isn't completed. The client keeps polling every 10 seconds and continues to poll for two minutes. After two minutes, the server sends the failed status if the otpCode verification isn't successful.

{
    "status": "pending",
    "cause": [
        {
            "code": "AUTH-1109",
            "message": "Enrollment in the One-Time Passcode authentication method is pending verification."
        }
    ],
    "nextOp": [
        "credSubmit",
        "createToken",
        "createSession",
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": false
    },
    "requestState": "1bYZJeyi6bcp..........74RXYKmbdiZfVW8y7tNc"
}

Step 5: Create the Authentication Token 🔗

This step indicates that the client is done with all authnFactors and needs a session created. The server validates that no other factor evaluation (depending on what is defined for the policy) is needed and responds with the token or denies access. The client must include the following attributes:

• op: tells the server what kind of operation the client wants

• requestState: received in the Step 4 response

Request Example

{  
   "op":"createToken",
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "authnToken": "{{authnToken}}",
    "status": "success"
}

Step 1: Begin the Authentication Flow 🔗

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format:

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

In the response, the nextOp value indicates what can be sent as the op value in the next request. In this use case example, credSubmit should be sent in the next step. The requestState contains contextual data needed to process the request.

Step 2: Submit the User's Credentials 🔗

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "R^iCq18G000000000",
    "accRecEnrollmentRequired": true,
    "nextAuthFactors": [
        "SMS",
        "SECURITY_QUESTIONS",
        "EMAIL"
    ],
    "SMS": {
        "credentials": [
            "phoneNumber",
            "countryCode"
        ]
    },
    "EMAIL": {
        "userAllowedToSetRecoveryEmail": "true",
        "primaryEmailVerified": "true",
        "primaryEmail": "clarence.saladna@example.com",
        "credentials": [
            "recoveryEmail"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "IjhvZPILfadhlnih+4uTJ83CHf....0SDELTO0mTRqC+nNU"
}

In this use case example, the user must enroll in account recovery (indicated by a value of true for the accRecEnrollmentRequired:true attribute). The nextAuthFactors indicates the factors in which the user can enroll for Account Recovery.

In this use case example, enrollment is sent in the next step to initiate account recovery enrollment for the user.

Step 3: Initiate Account Recovery Enrollment 🔗

This step initiates SMS enrollment. The client must include the following attributes:

• op: tells the server what kind of operation the client wants
• authFactor: defines which authentication factor that the user wants to enroll in
• phoneNumber: defines the phone number where the SMS text will be sent
• countryCode: defines the country code of the phone number where the SMS text will be sent
• requestState: received in the Step 2 response

Request Example

The following example shows the contents of the POST request in JSON format:

{  
   "op":"enrollment",
   "authFactor":"SMS",
   "credentials":{  
      "phoneNumber":"1122334455",
      "countryCode":"+44"
   },
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the request in JSON format:

{
    "status": "success",
    "ecId": "R^iCq19G000000000",
    "displayName": "+44XXXXXXXX455",
    "SMS": {
        "credentials": [
            "otpCode"
        ]
    },
    "nextOp": [
        "credSubmit",
        "resendCode",
        "enrollment"
    ],
    "requestState": "Y4sMHf7izgxcspF6zr...Y3GXLjjudeRMM2ZNty4E"
}

In the response, the nextOp values indicate what can be sent as the op value in the next request. In this use case example, credSubmit is sent in the next step. The otpCode is sent using SMS to the user's device.

Step 4: Submit Factor Credentials 🔗

Request Example

The following example shows the contents of the POST request in JSON format to submit the factor credentials:

{  
   "op":"credSubmit",
   "credentials":{  
      "otpCode":"974311"
   },
   "requestState":"{{requestState}}"
}

Response Example

The success status appears in the response when the optCode verification is successful. The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "R^iCq1BG000000000",
    "accRecEnrollmentRequired": false,
    "displayName": "+44XXXXXXXX455",
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "BKbGp43pwZad3zMSePWu7R47Va6myZdNY...vRVFN2FFQKIoDto"
}

In the response, the accRecEnrollmentRequired value is set to false as account enrollment is successful. The nextOp values indicate what can be sent as the op value in the next request. The nextOp value "enrollment" allows the user to switch to another factor to enroll in account recovery. In this use case example, createToken is sent in the next step.

Step 5: Create the Authentication Token 🔗

Request Example

The following example shows the contents of the POST request in JSON format:

{  
   "op":"createToken",
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "authnToken": "{{authnToken}}",
    "status": "success",
    "ecId": "R^iCq1FG000000000"
}

Step 1: Begin the Authentication Flow 🔗

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format:

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "ecId",
 "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "example-password"
        ]
    },
    "requestState": "{{requestState}}"
}

In the response, the nextOp value indicates what can be sent as the op value in the next request. In this use case example, credSubmit should be sent in the next step. The requestState contains contextual data needed to process the request.

Step 2: Submit the User's Credentials 🔗

{
   "op": "credSubmit",
   "credentials": {
      "username": "{{username}}",
      "password": "{{password}}"
   },
   "requestState": "{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1M0000000000",
    "accRecEnrollmentRequired": true,
    "nextAuthFactors": [
        "SMS",
        "SECURITY_QUESTIONS",
        "EMAIL"
    ],
    "SMS": {
        "credentials": [
            "phoneNumber",
            "countryCode"
        ]
    },
    "EMAIL": {
        "userAllowedToSetRecoveryEmail": "true",
        "primaryEmailVerified": "true",
        "primaryEmail": "clarence.saladna@example.com",
        "credentials": [
            "recoveryEmail"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "wtyRQpBzFZnuGMQvLNRotKfRIlgliWNc8sxipU....41zjKQcvdzk2bmvWs"
}

In this use case example, the user must enroll in account recovery (indicated by a value of true for the accRecEnrollmentRequired:true attribute). The nextAuthFactors indicates the factors in which the user can enroll for Account Recovery.

In this use case example, enrollment is sent in the next step to initiate account recovery enrollment for the user.

Step 3: Initiate Account Recovery Enrollment 🔗

This step initiates SMS enrollment. The client must include the following attributes:

• op: tells the server what kind of operation the client wants
• authFactor: defines which authentication factor that the user wants to enroll in
• phoneNumber: defines the phone number where the SMS text will be sent
• countryCode: defines the country code of the phone number where the SMS text will be sent
• requestState: received in the Step 2 response

Request Example

The following example shows the contents of the POST request in JSON format:

{  
   "op":"enrollment",
   "authFactor":"SMS",
   "credentials":{  
      "phoneNumber":"1122334455",
      "countryCode":"+44"
   },
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the request in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1N0000000000",
    "displayName": "+44XXXXXXXX213",
    "SMS": {
        "credentials": [
            "otpCode"
        ]
    },
    "nextOp": [
        "credSubmit",
        "resendCode",
        "enrollment"
    ],
    "requestState": "FnwYT23S0qo+RHXN3Sx80D3....8CsoT3QezVbynT3LfZY3+sXN5E8OtEdM"
}

In the response, the nextOp values indicate what can be sent as the op value in the next request. In this use case example, credSubmit is sent in the next step. The otpCode is sent using SMS to the user's device. Credentials tell the user what input is needed to pass in the next request.

Step 4: Submit Factor Credentials 🔗

Request Example

The following example shows the contents of the POST request in JSON format to submit the factor credentials:

{  
   "op":"credSubmit",
   "credentials":{  
      "otpCode":"974311"
   },
   "requestState":"{{requestState}}"
}

Response Example

The success status appears in the response when the optCode verification is successful. The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1P0000000000",
    "accRecEnrollmentRequired": false,
    "displayName": "+44XXXXXXXX455",
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "Z+ysro8gFyPPT5bI9C/RykLfRrq5rBXCOO68/wZcgkllw765qd7SNvhRN6ZHp0Xiw2FIN9nOeio7SpsEAlYxO2xQ/1fF5lAjo0jwJEzIgSRt8xj/vAQeSLhX+PRm2a1rRYHwSa9uFcUBkNA.....KP7CPh2/yrdZF4WpbI"
}

In the response, the accRecEnrollmentRequired value is set to false as account enrollment is successful. The nextOp values indicate what can be sent as the op value in the next request. The nextOp value "enrollment" allows the user to switch to another factor to enroll in account recovery. In this use case example, createToken is sent in the next step.

Step 5: Create the Authentication Token 🔗

Request Example

The following example shows the contents of the POST request in JSON format:

{  
   "op":"createToken",
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1Q0000000000",
    "nextAuthFactors": [
        "TOTP",
        "SECURITY_QUESTIONS",
        "SMS",
        "EMAIL",
        "PUSH"
    ],
    "EnrolledAccountRecoveryFactorsDetails": {
        "SMS": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "deviceId": "3ed9b2ed366441fb91c9277abd694348",
                    "displayName": "+44XXXXXXXX455"
                }
            ]
        },
        "EMAIL": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "displayName": "clarence.saladna@example.com"
                }
            ]
        },
        "enrolledAccRecFactorsList": [
            "SMS",
            "EMAIL"
        ]
    },
    "nextOp": [
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": true
    },
    "requestState": "YN9sdSJiNtD5lOEKt33paDa9Ezs5ZZhZhF3C1BsDCuMdVVNqt1RmA3d3SppmnVOIP3uYrErQNYADHCIQLrXgmxpxReUzdcFDArlejaaph3qWctYvLQiIsBwixsHgTOfQiDkzyjN8JZiX/gqbkTEmHi1S3EtjYXuw7qCcwi...G8ZnyfTrcZtKEpaDDj7CtWF/+LIwAEQLvFaXvkOK4P4"
}

In the response, as MFA is required, enrollmentRequired has a value of true under mfaSettings. As a result, no token is issued. The EnrolledAccountRecoveryFactorsDetails shows the account recovery factors the user has enrolled in. The nextOp values indicate what can be sent as the op value in the next request. In this example, the nextOp value "enrollment" indicates that the user is to enroll in MFA.

Step 6: Set SMS as Default MFA Factor in Overlap 🔗

This step indicates that the client should enroll in MFA.

The client must include the following attributes:

• authFactor: indicates which factor to enroll in for MFA
• accountRecoveryFactor: when set to true, indicates that the user want to reuse already enrolled account recovery factor for MFA.

Request Example

The following example shows the contents of the POST request in JSON format:

{ 
 "op":"enrollment",
 "authFactor": "SMS",
 "credentials":{ 
  "accountRecoveryFactor" : true 
 },
 "requestState": "{{requestState}}"
}

Response Example

{
    "status": "success",
    "ecId": "HI^kd1R0000000000",
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "7J6m/Z1PxXQZp4pigzt1F0CXp0kotX.....WXP2knQa16MNj5E8"
}

In the response the nextOp values indicate what can be sent as the op value in the next request. The nextOp value "enrollment" allows the user to enroll additional factor for MFA. In this use case example, createToken is sent in the next step.

Step 7: Create the Authentication Token 🔗

Request Example

The following example shows the contents of the POST request in JSON format:

{  
   "op":"createToken",
   "requestState":"{{requestState}}"
}

Response Example

{
    "authnToken": "{{authnToken}}",
    "status": "success",
    "ecId": "HI^kd1W0000000000"
}

Before You Begin 🔗

Step 1: Enable KMSI for an Identity Domain 🔗

1. Get the identity domain admin access token for your account.
2. Run GET on the /admin/v1/KmsiSettings/KmsiSettings endpoint. The system returns the KmsiSettings.
3. Update the necessary attributes and run PUT on the /admin/v1/KmsiSettings/KmsiSettings endpoint.

tokenValidityInDays

Enter how many days users can stay signed in before they're automatically signed out.

kmsiEnabled

Indicates whether KMSI is enabled for the identity domain.

maxAllowedSessions

Enter the maximum number of signed-in sessions that a user can have.

Example Request

{
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:KmsiSettings"
    ],
    "tokenValidityInDays": 2160,
    "kmsiEnabled": true,
    "maxAllowedSessions": 5,
    "id": "KmsiSettings"
}

Step 2: Begin the Authentication Flow 🔗

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format:

   curl  -X GET
   -H "Content-Type: application/json" 
   -H "Authorization: Bearer {{access_token_value}}"
   https://<domainURL>/sso/v1/sdk/authenticate?appName={{app_name}}

Response Example

{
    "status": "success",
    "ecId": "ZzK2c1^0000000000",
    "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "password"
        ]
    },
    "keepMeSignedInEnabled": false,
    "requestState": "FT7qI"
}

Note the new keepMeSignedInEnabled attribute included in the response. This indicates that this identity domain and application supports KMSI. If you have a custom interface, use this attribute to show the Keep me signed in option in the sign-in page.

Step 3: Submit the User's Credentials with KMSI 🔗

{
    "op": "credSubmit",
    "credentials": {
        "username": "username",
        "password": "Password"
    },
    "keepMeSignedIn": true,
    "kmsiDeviceDisplayName": "Postman KeepMeSigned In",
    "requestState": "requestState"
}

If you have a custom interface, use this attribute to show the KMSI option, check the status of the checkbox (on or off) and send this parameter to create the KMSI session.

Response Example

{
    "authnToken": "QpfQIQ",
    "kmsiToken": "ZJM",
    "status": "success",
    "ecId": "PR8Yf160000000000"
}

In the response example, note the kmsiToken attribute. This token can be used to access any applications in the future without requiring a user to sign in again.

Step 4: Reissue authnToken After Session Expiry 🔗

Request Example

{
    "op": "credSubmit",
    "authFactor": "KMSI",
    "appName": "AppName",
    "kmsiToken": "{{kmsiToken}}"
}

Response Example

{
    "authnToken": "QpfQIQ",
    "kmsiToken": "ZJM",
    "status": "success",
    "ecId": "PR8Yf160000000000"
}

Note the operation credSubmit with a new authFactor, appName and kmsiToken being sent in the request. SSO evaluates the request and returns authnToken and latest updated kmsiToken in the response. This is a refreshed kmsiToken and replaces the existing token. You must include this refreshed kmsiToken in the next request.

Step 5: Submit User's Credentials with KMSI and MFA Flow 🔗

Initiate GET on /sso/v1/sdk/authenticate from Step 2: Begin the Authentication Flow.

Response Example

{
    "op": "credSubmit",
    "credentials": {
        "username": "username",
        "password": "Password"
    },
    "keepMeSignedIn": true,
    "kmsiDeviceDisplayName": "Postman KeepMeSigned In",
    "requestState": "requestState"
}

Response Example

{
    "status": "success",
    "ecId": "L371Y0xD000000000",
    "displayName": "sswXXXXX@oracle.com",
    "nextAuthFactors": [
        "EMAIL-OTP/TOTP/SMS-OTP/PUSH/BYPASSCODE"
    ],
    "EMAIL-OTP/TOTP/SMS-OTP/PUSH/BYPASSCODE": {
        "credentials": [
            "otpCode"
        ]
    },
    "nextOp": [
        "credSubmit",
        "getBackupFactors",
        "resendCode"
    ],
    "scenario": "AUTHENTICATION",
    "requestState": "QQwppp+-",
    "trustedDeviceSettings": {
        "trustDurationInDays": 15
    }
}

After you get the one-time passcode (OTP) on the device, add the OTP in the request.

Request Example

{
    "op": "credSubmit",
    "authFactor": "EMAIL-OTP/TOTP/SMS-OTP/PUSH/BYPASSCODE",
    "credentials": {
        "otpCode": "XXXX"
    },
    "requestState": "6tnX6Q4RGqe4Lq73WD0pQ"
}

The response includes authToken and kmsiToken. This is a refreshed kmsiToken.

Response Example

{
    "authnToken": "QpfQIQ",
    "kmsiToken": "ZJM",
    "status": "success",
    "ecId": "PR8Yf160000000000"
}

Step 6: Reissue authnToken After Session Expiry When an MFA Factor Is Set 🔗

When a user tries to sign in using kmsiToken and there's a second factor configured, then the user is always prompted for authentication of the second factor. Only after successful authentication, will authnToken and kmsiToken be sent in the response.

Request Example

{
    "op": "credSubmit",
    "authFactor": "KMSI",
    "appName": "AppName",
    "kmsiToken": "{{kmsiToken}}"
}

The response contains a refreshed KMSI token and an MFA challenge.

Response Example

{
    "status": "success",
    "ecId": "pccFR1eG000000000",
    "displayName": "XXXXX@oracle.com",
    "nextAuthFactors": [
        "EMAIL-OTP/TOTP/SMS-OTP/PUSH/BYPASSCODE"
    ],
    "EMAIL-OTP/TOTP/SMS-OTP/PUSH/BYPASSCODE": {
        "credentials": [
            "otpCode"
        ]
    },
    "nextOp": [
        "credSubmit",
        "getBackupFactors",
        "resendCode"
    ],
    "scenario": "AUTHENTICATION",
    "requestState": "+Dj6hQQ7id5V2gSGHGtCROb5n",
    "trustedDeviceSettings": {
        "trustDurationInDays": 15
    },
    "kmsiToken": "fxkLne3RtKI1c"
}

Repeat the same process where you will again prompted for the OTP on the device. Provide the below payload with the OTP. The response should include the authnToken.

Request Example

{
    "op": "credSubmit",
    "authFactor": "EMAIL-OTP/TOTP/SMS-OTP/PUSH/BYPASSCODE",
    "credentials": {
        "otpCode": "XXXX"
    },
    "requestState": "6tnX6Q4RGqe4Lq73WD0pQ"
}

Response Example

{
    "authnToken": "QpfQIQ",
    "status": "success",
    "ecId": "PR8Yf160000000000"
}

kmsiToken Flow with requestState 🔗

Use this flow to support browser context when you possess the KMSI token but not the KMSI cookie. After session expiry, the application makes an authorization call to the identity system with the redirectUrl, state, nonce, and so on. In the response, the identity system returns the requestState inside loginCtx. This requestState along with KMSI token is passed to redirect the required application after extending the session.

Request Example

{
    "op": "credSubmit",
    "authFactor": "KMSI",
    "appName": "KMSIAdmin",
    "kmsiToken": "{{kmsiToken}}",
    "requestState": "{{requestState}}"
}

Response Example

{
    "authnToken": "QpfQIQ",
    "kmsiToken": "ZJM",
    "status": "success",
    "ecId": "PR8Yf160000000000"
}

Changes to /sso/v1/sdk/secure/session 🔗

KMSI requires a new attribute be added to the /sso/v1/sdk/secure/session endpoint. kmsiToken must be sent to the endpoint from the custom login application.

Payload Signature for /authorize Initiated Calls 🔗

1. When a user accesses any web application protected by identity domains, they enter their application URL, for example, https://example.com/home/pages/profile.
2. The system redirects to the identity domain /authorize call.
3. The identity domain redirects the user to customer deployed custom sign-in page.
4. The customer hosted sign-in application collects the input parameters and decodes loginCtx input.
5. The decrypted input parameter matches with the GET /sso/v1/sdk/authenticate call.
6. The payload contains keepMeSignedInEnabled to identify whether KMSI is enabled.
7. The custom login application collects the credentials and submits it to the identity domain.
8. The identity domain validates the credentials and issues kmsiToken and authnToken.
9. The custom login application makes use of the authnToken and kmsiToken while making call to /sso/v1/sdk/secure/session endpoint. The new syntax of the secure endpoint is described in Changes to /sso/v1/sdk/secure/session.
10. The identity domain validates the authnToken, kmsiToken and then the identity system issues the SSO session cookie and the KMSI cookie.
11. During the session, the KMSI cookie is validated to extend the session without re-entering the credentials.