Authenticate

Oracle MICROS APIs use the OpenID Connect authentication framework. API users send a request to the OpenID provider. The OpenID provider authenticates the account and responds with an id_token and a refresh token. The client can then send a request with the id_token to the API endpoints.

Oracle Identity Management provides a URL for external systems to dynamically discover and interact with the OpenID provider in a standardized way, as shown in the following example:

https://<host_environment_URL>/oidc-provider/v1/.well-known/openid-configuration

See OpenID Provider Metadata specification for more information on metadata values that describe the configuration of the OpenID provider.

Successful OAuth transactions require the Oracle OpenID provider to issue an id_token for authenticating an API call. An id_token represents an authorization issued to the client application containing credentials used to access protected OAuth resources.

The following image shows the tasks in this section that only need to be completed once.

The following image shows the tasks in this section that might be completed more than once.

Task 1: Create a Business Intelligence API Account

Create a Business Intelligence API account in Oracle MICROS Reporting and Analytics as described in Obtain Account Information.

Task 2: Authorize with OpenID

Authorize the account with the OpenID provider to sign in with the API account. This step is required to subsequently sign in to the API account.

1. Generate a code_verifier.

   A code_verifier is a cryptographic string that is Base64 encoded. Example:

   // Dependency: Apache Commons Codec
   // https://commons.apache.org/proper/commons-codec/
   // Import the Base64 class.
   // import java.util.Base64;
   SecureRandom sr = new SecureRandom();
   byte[] code_string = new byte[32];
   sr.nextBytes(code_string);
   String code_verifier = Base64.getUrlEncoder().withoutPadding().encodeToString(code_string);

2. Generate a code_challenge.

   A code_challenge is a cryptographic key that encrypts the code_verifier using SHA256 algorithm. Example:

   // Dependency: Apache Commons Codec
   // https://commons.apache.org/proper/commons-codec/
   // Import the Base64 class.
   // import org.apache.commons.codec.binary.Base64;
   byte[] verifier_bytes = code_verifier.getBytes("US-ASCII");
   MessageDigest msgdigest = MessageDigest.getInstance("SHA-256");
   msgdigest.update(verifier_bytes, 0, verifier_bytes.length);
   byte[] digest = msgdigest.digest();
   String challenge = Base64.encodeBase64URLSafeString(digest);

3. Authorize with OpenID.

   The client application must invoke the following API for OpenID authorization to get an authorization_code. The following table describes the components that comprise the request for an authorization_code:

   Request

   API Request Parameters	Description	Example
   URL	URL for the authorize API. Replace {HOST} with the actual host server name and port where the Authentication Server is hosted for the enterprise. See Send Requests for more details.	{HOST}/oidc-provider/v1/oauth2/authorize
   Operation Type	HTTP GET request type.	GET
   cookiefilename	Temporary file name to save the cookies in the response.	<cookiefilename>
   Query Parameters	List of query parameters. See next table for parameters.

   Query Parameter	Description	Example
   response_type	Set to code.	code
   client_id	OAuth 2.0 Client Identifier that is generated when the API account was created.	<client_id>
   scope	Set to openid.	openid
   redirect_uri	Set to apiaccount://callback.	apiaccount://callback
   code_challenge	This is a 43-128 character-long client-generated string. This string must first be hashed using SHA-256 and then Base 64 encoded. Use the code_challenge that was generated in previous step.	H9K........Ik
   code_challenge_method	Set to S256.	S256

   Sample Request

   curl -c <cookiefilename> --request GET "{HOST}/oidc-provider/v1/oauth2/authorize?response_type=code&client_id=NTAzMDQ0NjItNzA5Yy00YjZlLWI0NjItN2U1YWRhZDBmYzcxLmE4OGM4Njg0LTNmMmMtNGFlYS1hMjdjLTdhZTU4MTJhYzIwNw%3D%3D&scope=openid&redirect_uri=apiaccount://callback&code_challenge=H9KVBZo4Zwa_rRR_X-KyfycPWuP2417K15w42JqsAIk&code_challenge_method=S256"

   Sample Response

   A successful request creates a temporary cookie file that saves the cookies required for subsequent API calls.

   HTTP/1.1 200 OK

   Sample Cookie File Contents

   #HttpOnly_{HOST}      FALSE   /       FALSE   0       redirect_uri    apiaccount://callback
   #HttpOnly_{HOST}      FALSE   /       FALSE   0       client_id       NTAzMDQ0NjItNzA5Yy00YjZlLWI0NjItN2U1YWRhZDBmYzcxLmE4OGM4Njg0LTNmMmMtNGFlYS1hMjdjLTdhZTU4MTJhYzIwNw==
   #HttpOnly_{HOST}      FALSE   /       FALSE   0       response_type   code
   #HttpOnly_{HOST}      FALSE   /       FALSE   0       state
   #HttpOnly_{HOST}      FALSE   /       FALSE   1601465478      code_challenge  H9KVBZo4Zwa_rRR_X-KyfycPWuP2417K15w42JqsAIk
   #HttpOnly_{HOST}      FALSE   /       FALSE   1601465478      code_challenge_method   S256

   Sample Error Response

   The following example shows an error caused by invalid input in the request:

   HTTP/1.1 400 Bad Request
   Content-Type: application/json
   {
       "status":400,
       "message":"INVALID_CLIENT",
       "code":"VALIDATION_ERRORS"
   }

Task 3: API Account Sign-In

The client application must submit the API account's sign-in credentials to the server. Upon successfully signing in, the system returns a response with an authorization code that can be exchanged for an id_token in the following task.

Note:

The API account password expires after 60 days. To reset your password either before or after expiration, click Can't sign in on the Reporting and Analytics sign-in page.

Request

Invoke the API request below and pass the required information for obtaining an authorization code. The following table describes the components that comprise the request for an authorization code:

API Request Parameters	Description	Example
URL	URL for the Sign in API. Replace {HOST} with the actual host server name and port where the Authentication Server is hosted for the enterprise. See Send Requests for more details.	{{HOST}}/oidc-provider/v1/oauth2/signin
Operation Type	HTTP POST request type.	POST
Header Parameters	Content type of the header parameters request payload. Set to application/x-www-form-urlencoded.	application/x-www-form-urlencoded
Request Body Parameters	List of request body parameters. See next table for parameters.
cookiefilename	Temporary file name to save the cookies in the response.	cookiejar20201020

Request Body Parameters	Description	Example
username	API account's username.	apiuser1
password	API account's password.	Password@1
orgname	Organization short name of your Oracle MICROS Simphony enterprise.	ORG

Sample Request

curl -b <cookiefilename> --request POST "{HOST}/oidc-provider/v1/oauth2/signin" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "username=<apiaccountusername>" --data-urlencode "password=<apiaccountpassword>" --data-urlencode "orgname=<organizationshortname>"

Sample Successful Response

The response returns the authorization code (auth_code) in the redirectUrl attribute of the response if the request is successful.

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{"nextOp":"redirect","success":true,"redirectUrl":"apiaccount://callback?code=<auth_code>"}

Sample Response for a Locked Account

If you use the wrong account password too many times, the account becomes locked and the account owner receives an email. Try to sign in again in 30 minutes or reset the password by clicking Can't sign in on the Reporting and Analytics sign-in page.

{
    "status": 401,
    "message": "Invalid credentials.",
    "code": "AUTHENTICATION_INVALID"
}

Sample Response for Expired Password

If the account password expires, the response includes details in the nextOp, success, redirectURL, and error attribute values. To resolve this, update or reset the account password from the Reporting and Analytics sign-in page.

{
    "nextOp": "expired",
    "success": false,
    "redirectUrl": "<application server URL>",
    "userName": "<api account name>",
    "emailAddress": "<email address assigned to the api account>",
    "orgName": "<organization short name>",
    "opUserId": "<used for internal application purposes>",
    "orgId": <used for internal application purposes>,
    "tenantId": "<used for internal application purposes>",
    "language": "en-US",
    "pwdResetToken": "<used for internal application purposes",
    "error": "You must change your password."
}

Sample Error Response

The following example shows an error caused by invalid input in the request:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"status":401,"message":"Invalid credentials.","code":"AUTHENTICATION_INVALID"}

Task 4: Get or Refresh a Token

Once you have the authorization code, your client application needs an OAuth2.0-based ID token to make the API call. The ID token provides a session (with scope and expiration), that your client application uses to make API calls.

The token API returns an ID token and a refresh token. Your integration should save both.

• The ID token is used as the bearer token in the authorization header of all API calls. It is valid for 1,209,600 seconds = 14 days.

• Before the ID token expires, use the refresh token in the token API to get a new set of ID token and refresh token.

• Oracle recommends that you renew the token 3-7 days prior to its expiration.

• An expired ID token cannot be used to call any other API.

• An expired ID token cannot be refreshed because the refresh token uses the same expiration time.

Note:

A refresh token is included in the token API response when using the Authorization Code Flow with Proof Key of Code Exchange (PKCE). This refresh token should be used to obtain an updated set of tokens in perpetuity, instead of utilizing the full Authorization Code Flow with PKCE.

Request

Your application passes the following for obtaining a token:

API Request Parameters	Description	Example
URL	URL for the token API. Replace the {HOST} with the actual host server name and port where the Authentication Server is hosted for the enterprise. See Send Requests for more details.	{{HOST}}/oidc-provider/v1/oauth2/token
Operation Type	HTTP Request Type.	POST
Header Parameters	Content type of the header parameters request body. Set to application/x-www-form-urlencoded.	application/x-www-form-urlencoded
Request Body Parameters	List of request body parameters. See next table for parameters.	N/A

Request Body Parameters	Description	Example
scope	Set to openid.	openid
grant_type	Set to authorization_code to get a new token. Set to refresh_token to renew an expiring token and get a new id_token and refresh_token.	authorization_code refresh_token
client_id	The OAuth 2.0 Client Identifier that is generated when the API account is created.	NTAzMDQ.......Nw==
code_verifier	Plain text version (43-128 character-long string) of the code_challenge parameter in the signin API . Use the code_verifier generated in Task 2, Step 1.	H9KV.............AIk
code	Only needed to get the initial new token, set to the auth_code from signin call.	NTA...................Gg=
refresh_token	Use when refreshing existing token, set to refresh_token from previous call.	NTA...................Gg=
redirect_uri	Set to apiaccount://callback.	apiaccount://callback

Sample Request to Get a New Token

curl -b cookiefile -c cookiefile --request POST "{HOST}/oidc-provider/v1/oauth2/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "scope=openid" --data-urlencode "grant_type=authorization_code" --data-urlencode "client_id=<client_id>" --data-urlencode "code_verifier=<code_verifier>" --data-urlencode "code=<auth_code>" --data-urlencode "redirect_uri=apiaccount://callback"

Sample Request to Refresh a Token

curl -b cookiefile -c cookiefile
--request POST "{HOST}/oidc-provider/v1/oauth2/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "scope= openid" --data-urlencode "grant_type= refresh_token" --data-urlencode "client_id=<client_id>" --data-urlencode "refresh_token=<refresh_token>" --data-urlencode "redirect_uri=apiaccount://callback"

Sample Successful Response

The response returns the OAuth2.0 token string if the request is successful.

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{ 
	"access_token": "<access_token string>", 
	"token_type": "Bearer",
	"expires_in": "1209600", 
	"id_token": "<token string>", 
	"refresh_token": "<token string>"
}

Sample Error Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"status": 401,"message": "AUTHENTICATION_CODE_NOT_FOUND","code": "RECORD_NOT_FOUND"}

JSON Response

Contains the access token request output in JSON format. The response contains the attributes access_token, id_token, refresh_token, token_type, and expires_in.

API Request Response Body Parameters	Description	Example
id_token	Identifies your client access in Oracle and will be used for subsequent REST API calls. This token is encoded following the JSON Web Token (JWT) standard and is valid for 14 days.	NTAzMDQ.......Nw==
access_token	Not used.	N/A
token_type	Identifies the access token as a bearer token type. In future requests, you will use this token type to identify your token in the authorization header of your request. To use this token in your request, set the authorization key in the request header to Bearer <id_token>.	Bearer
expires_in	Identifies the validity period of the id_token in seconds.	1209600
refresh_token	Identifies the client access in Oracle and can be used to get a new id_token (using grant_type=refresh_token in the token API call) when the current one expires. The refresh_token is valid for 14 days.	HTAzNER.......Ov==

If you see the error AUTHENTICATION_INVALID after a Reporting and Analytics upgrade, clients should go through the authentication process again and obtain a new token.

You must repeat the authentication process if your client lost the ID token or the refresh token, or if the client missed a refresh to the token prior to its expiration. The password of the API account expires after 60 days and needs to be changed after that. The account password can be reset from the Reporting and Analytics sign-in page by clicking Can't sign in?.

Task 5: Using the id_token in API Calls

Once you have successfully received the authentication id_token, the client application can use the same to make API requests. Use the following header parameters to insert the id_token.

API Request Parameters	Description	Example
URL	URL for the BI API. Replace the {HOST} with the actual Host server name and port where Reporting and Analytics is hosted for the enterprise. See Send Requests for more details.	{{HOST}}/bi/v1/orgShortName/<API Name>
Operation Type	HTTP Request Type	POST

Header Parameters	Description	Example
Content-Type	Content type of the request body. Always set to application/x-www-form-urlencoded.	application/x-www-form-urlencoded
Authorization	Authorization method for the API request.	Bearer <id_token>

Sample Request

curl -i -X POST -H "Authorization: Bearer <id_token>" -H "Content-Type:application/json" -d "locRef":1234" -d "busDt:2020-10-20" {HOST}/bi/v1/orgidentifier/getCashManagementDetails

Sample Successful Response

HTTP/1.1 200 OK  Date: Tue, 20 Oct 2020 21:24:33 GMT  Transfer-Encoding: chunked  Content-Type: application/json
{
 
    "locRef":  "1234",
    "busDt": "2020-10-20",
    "revenueCenters":[{
        "rvcNum": 1372,
        "cmDetails":[{
            "cmItemNum": 1372,
            "receptacleType": 1,
            "receptacleName": "Safe",
            "receptacleNum": 123,
            "startAmt": 123.45,
            "transAmt": 123.45,
            "overShortAmt": 123.45,
            "depAmt": 1234.56
            "transUTC": "2020-10-20T15:59:59",
            "transEmpNum":1234,
            "refInfo": "Manually Entered Text",
            "transType": 1,
            "rsnCodeNum": 123,
            "wsNum": 123,
            "notes": "Notes",
            "othrAmt": 123.45
        }]
    }]
 
}