Oracle Fusion Applications Token Relay Authentication

What Happens During the Login Sequence?

The add-in performs the authentication process just prior to any business operation initiated by the business user that requires access to the REST service. The add-in uses an embedded web browser control to host the login interaction sequence between the workbook user and the Fusion Application (FA) authentication provider.

During a successful login, the add-in captures the necessary authentication tokens and then uses them with subsequent REST requests. In particular, the access token is sent using the Bearer authentication scheme in the Authorization header. For more information, see RFC 6750.

The add-in uses these endpoints to get the authentication token:

Endpoint	Example
UI home page	`https://<my-service-host>/fscmUI/faces/FuseWelcome`
Anti-CSRF endpoint	`https://<my-service-host>/fscmRestApi/anticsrf`
Token relay servlet endpoint	`https://<my-service-host>/fscmRestApi/tokenrelay.`

Note:

In most cases, <my-service-host> is the catalog host. If a Token Relay Host is configured, it is used instead. See Configure Token Relay Authentication for a Catalog.

The login sequence:

If the catalog is configured to use the "Default" authentication method, the add-in makes an initial ping request to the anti-CSRF endpoint.
- If the request returns a 404 or other error, then the add-in abandons the Token Relay authentication mechanism and falls back to using Basic authentication.
- If the request returns a 200, with content-type application/json, and the payload contains a non-empty xsrftoken member, then the add-in proceeds with the login sequence.
Note:
If the catalog is configured to use the "Oracle Fusion Application Token Relay" authentication method, the initial ping to the anti-CSRF endpoint is skipped. The ping occurs later during page navigation.
The add-in displays a modal pop-up login window that contains an embedded browser control, and directs the browser control to navigate to the UI Home Page URL. See The Embedded Browser.
Since the business user has not yet successfully logged in, the browser is redirected to a page with a login form. This form typically contains user name and password fields and a Submit button.
The login user interface pages are controlled by the FA environment. There could be multiple steps involved, such as SSO, multi-factor authentication, and so on.
Each time a user's gesture or login page logic causes a page navigation event in the browser, the add-in's event handler is notified and the add-in performs an authentication test to see whether the user has logged in. See Token Relay Authentication Test.
- If the user has successfully logged in, the login sequence is complete. The add-in automatically closes the login window and can continue with the REST request that triggered the login sequence using the harvested authentication tokens.
- If the user has not yet logged in, the login window remains visible and the add-in continues listening for page navigation events.
- If the user closes the login window before logging in successfully, the operation that initiated the authentication process is canceled.

Token Relay Authentication Test

The add-in watches for page transitions in the embedded browser and performs a Token Relay authentication test to see if the user has successfully logged in. If the add-in can get a token from the Token Relay servlet using cookies from the embedded browser, then the user has successfully authenticated.

Details about the test:

When each page navigation event is raised from the browser, the add-in sends a GET request to the anti-CSRF endpoint in order to get an anti-CSRF token.
Once an anti-CSRF token is obtained, the add-in skips this step on subsequent page navigation events.
The add-in then makes a GET request to the Token Relay servlet endpoint. This request includes the ScopesFQ value, if configured. If the request is denied, the test fails. Otherwise, on a 200 OK with a response payload of content-type application/json:
1. The payload is parsed and validated. The access_token member must be present and non-empty.
2. The value for access_token is captured in memory and used for subsequent REST requests.
3. If the parsing succeeds, the test is considered to have passed. The login window is closed, and the target REST request continues.
4. Otherwise, the test is considered to have failed and the login window remains open.

Configure Token Relay Authentication for a Catalog

When you configure token relay authentication, you're prompted to provide values for two optional configuration properties: Token Relay Host and ScopesFQ. If your REST service doesn't require values for these settings, you can leave them blank.

Provide a Token Relay Host value if the Fusion Applications token relay service is located on a different host than your REST service. If these services are both hosted on the same pod, you can leave this field blank and Oracle Visual Builder Add-in for Excel will use the catalog's host instead.

Provide a ScopesFQ value if you want to append a scopesfq query parameter value when calling the token relay service. If you leave this field blank, the add-in does not include the scopesfq query parameter.

Consult with your REST service owner or refer to the documentation for your target REST service to determine the appropriate values for these properties.

These optional authentication properties can be configured when you create a catalog during layout creation. They can also be configured for an existing catalog from the Business Object Catalog Editor.

To configure token relay authentication during new layout creation:

Launch the New Layout Setup wizard as described in either Create a Table Layout in an Excel Workbook or Create a Form-over-Table Layout in an Excel Workbook.
From the first screen of the wizard, select Oracle Fusion Applications Token Relay from the Authentication list, then click Next.

The wizard displays a screen for entering token relay properties. This image shows the screen with sample values in the screen's fields.

Description of the illustration token-relay-config.png

Note:
You can also access this screen for an existing catalog from the Advanced page of the Business Object Catalog Editor. To open this screen, select Oracle Fusion Applications Token Relay from the Authentication list, then click Edit Authentication Flow Properties. See Set an Authentication Method for a REST Service.
If the Fusion Applications token relay service is located on a different host than the REST service, type the token relay host in the Token Relay Host field.

The host should use this format: <protocol>://<host>:<port>. For example:

https://my-pod.fa.ocs.oraclecloud.com:443

Note:
Do not include the path to the Fusion Applications token relay service.
If you want to include a scopesfq query parameter, type it in the ScopesFQ field.
If you include a value here, the add-in URL-encodes this value and adds it as the scopesfq query parameter value when calling the token relay service.
Click Next to proceed through the New Layout Setup wizard.

The sample values in the image results in this URL (with URL encoding omitted for readability):

https://my-pod.fa.ocs.oraclecloud.com:443/fscmRestApi/tokenrelay?scopesfq=urn:opc:resource:fusion:xxx:erp/

Requirements for Token Relay Authentication

Before configuring Token Relay Authentication for an integrated workbook's catalog, review these requirements:

The UI Home Page must be protected in such a way that an unauthenticated request in a browser redirects the browser and initiates a login sequence by redirecting to a login page.
The /anticsrf endpoint should allow anonymous ("unauthenticated") access. The response payload must contain the token in the xsrftoken member.
The /tokenrelay endpoint must be protected so that only authenticated users, identified by cookies issued during the browser login sequence, may access it.
Oracle Fusion Applications Token Relay is only supported for Oracle Cloud Application deployments that include standardized /anticsrf and /tokenrelay endpoints with standardized payloads.