4 Understanding AIS Authentication

This chapter contains the following topics:

4.1 Overview

The AIS Server uses EnterpriseOne authentication to authenticate AIS clients. All AIS sessions are established with requests to the EnterpriseOne HTML Server to establish a corresponding HTML Server (JAS) session. The AIS Server can maintain open sessions linked to open JAS sessions. It can also execute stateless calls where sessions are temporarily established only for the time of the call and thereafter terminated.

You can configure the AIS Server to use SSL so that all communication is over HTTPS. It can also be configured to communicate over HTTPS with the EnterpriseOne HTML Server.

The AIS Server supports the following authentication methods or login types:

  • Username and Password

    This login type is used in JD Edwards EnterpriseOne mobile enterprise applications for authentication.

  • Basic Authentication

    This login type is used for authenticating Internet of Things (IoT) devices calling orchestrations on the AIS Server. It is also used by the EnterpriseOne Orchestrator Client to test running orchestrations on the AIS Server.

  • PS Token

    This login type is used in EnterpriseOne ADF applications. It is also used by EnterpriseOne Pages designed to call AIS services through the e1pagehelper.js API.

  • JSON Web Token (Release 9.2.0.5)

    This login type can be used in a JD Edwards EnterpriseOne mobile application integration with Oracle Mobile Cloud Service. You can also use this login type to employ OAuth 2.0 authentication for third-party AIS clients, including clients developed using the AIS Client Java API to call AIS services and orchestrations on the AIS Server.

    Note:

    You can use OAuth 2.0 if you have an EnterpriseOne configuration with Oracle Access Manager (OAM), where OAM is the OAuth provider.

Starting with Tools 9.2.4, you have an option to use Header based authentication. You can use the Header based authentication method for requesting an AIS token and using an AIS token.

Requesting a Token

The /tokenrequest service has three HTTP headers that can be used in conjunction with Basic Authorization or JWT token request to indicate the environment, role and device that the session is established with. You can include the following authentication credentials in the Request Header instead of passing these values in the response body:

jde-AIS-Auth-Environment

jde-AIS-Auth-Role

jde-AIS-Auth-Device

Example

POST to /tokenrequest they would look like this:

POST /jderest/v2/tokenrequest HTTP/1.1

Accept: application/json

Content-Type: application/json

jde-AIS-Auth-Environment: JDV920

jde-AIS-Auth-Role: *ALL

jde-AIS-Auth-Device: Postman

Authorization: Basic S09VOktPVQ==

Using a Token

To use a token, all the AIS services allow two HTTP headers for passing the token and device name. You can include the following authentication in the Request Header instead of passing these values in the response body. Device name is optional. However, if the token was requested with device name, the authentication must be used with device name.

jde-AIS-Auth

jde-AIS-Auth-Device

Example

POST to /formservice they would look like this:

POST /jderest/v2/formservice HTTP/1.1

Accept: application/json

Content-Type: application/json

jde-AIS-Auth: 0449gCaVHmzYCg3/+3qobSsCukOavk5Xvrn7E8c/VNsP4I=MDE5MDEzMTMwMjQ0NzY0NDQ1MTkwNTY0MU5pY29sZVBvc3RtYW4xNTYxNDgyMzE5Nzgy

jde-AIS-Auth-Device: Postman

You must make sure that the authentication method or login type used by an AIS client is enabled in the Application Interface Services Security Settings section in Server Manager. Figure 4-1 shows the AIS Server login type settings in Server Manager, which include:

  • Allow JWT Token Login

  • Allow Basic Authentication Login

  • Allow PS Token Login

  • Allow Username and Password Login

Figure 4-1 Allowed Login Type Settings for the AIS Server

Surrounding text describes Figure 4-1 .

4.2 Session Management

After a token request is sent to the AIS Server with successful authentication, the AIS Server generates a token and maintains a session for the user session according to the time out and time-to-live settings in Server Manager (rest.ini). A corresponding user session is also maintained on the EnterpriseOne HTML Server. You can view the AIS sessions in Server Manager, which displays "AIS Server" in the Display Mode for active AIS sessions. The AIS token is the key to the user session and must be passed on to all subsequent calls that use that AIS session.

For stateless AIS requests, credentials are supplied (not AIS tokens). Requests are given a temporary session that is removed after a request completes.

The original security model for mobile applications still applies, even for non-mobile clients. The deviceName (or Device ID) is not required. If Device ID is not passed, the requesting IP address is used. Thus a token requested from one device or IP address cannot be used by another device or IP address. Validation is performed every time the token is used.

4.3 Configuring OAuth 2.0 Resource Servers with OAM 11g

You can use an OAuth 2.0 resource server to handle the authentication requests from AIS clients. This type of authentication allows access to AIS services, as well as orchestrations created using the Orchestration Studio. In this authentication process, an OAuth token is requested from an authentication provider and then passed to the AIS token request (stateful) or AIS service directly (stateless). If the AIS token request (stateful) is used, the AIS token is used for subsequent AIS calls.

To use OAuth 2.0, the format of the OAuth 2.0 token must be JWT and you must configure the steps required for JWT configuration.

See "Configuring EnterpriseOne HTML Server for JSON Web Token (JWT) (Release 9.2.3.2)" or "Configuring EnterpriseOne HTML Server for JSON Web Token (JWT) (Release 9.2.0.5)" in the JD Edwards EnterpriseOne Tools Security Administration Guide.

Figure 4-2 shows OAuth 2.0 authentication flow for stateful scenario.

Figure 4-2 OAuth 2.0 Authentication Flow for Stateful Scenario

Description of Figure 4-2 follows
Description of ''Figure 4-2 OAuth 2.0 Authentication Flow for Stateful Scenario''

The following steps describe the configuration and authentication flow:

  1. Create an OAuth 2.0 resource server.

    See Section 4.3.1, "Creating an OAuth 2.0 Resource Server" for more information.

    See Section 4.3.2, "Creating an OAuth 2.0 Client" for more information.

  2. Get an OAuth 2.0 token using the registered client ID, secret, domain, and scope.

    The following is an example of the parameters that you would provide to generate an OAuth 2.0 token. In this example, the value passed for Authorization parameter 'SkRFOnBsNEhBYzg5' is a base64 encoded value of client ID and secret that is separated by a colon.

    curl -i -H 'Authorization: Basic <SkRFOnBsNEhBYzg5'> -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "X-OAUTH-IDENTITY-DOMAIN-MAME:<JDEIdentityDomain>" --request POST http://mycompany.com:14100/oauth2/rest/token -d 'grant_type=client_credentials&scope=<JDEResourceServer>'.

    Parameter Value Description
    Authorization Header Basic <base34_clientid_secret> This parameter contains base64 encoded values of the client ID and client secret separated by colon. The parameter is used as access token by the client.
    Client ID <client_id> This parameter is the unique API key that is generated when you register your application with OAM.
    Client Secret <client_secret> This parameter is the private key that is generated when you register your application with OAM.
    Access Token URL ms_oauth/oauth2/endpoints/oauthservice/tokens This parameter is an endpoint that is used to obtain an access token from OAM.
    Grant Type client_credentials This parameter indicates that the REST API to be invoked is owned by the client application.
    Scope JDEResourceServer This parameter returns all the grants provided to your application.
    Domain JDEIdentityDomain This parameter is the Identity Domain name under which all clients and resource servers are created.

  3. An OAuth 2.0 token is generated with the client ID, secret, and scope and sent in the Bearer header of an AIS token request. (Stateless requests are also supported.)

  4. The AIS Server forwards the OAuth 2.0 token to the EnterpriseOne HTML Server and is configured to allow a JWT. The AIS Server forwards the OAuth 2.0 token in the Bearer if login is required.

  5. The Security Server checks the PS Token with node trust, and returns an authorization response to the EnterpriseOne HTML Server. You must import the OAM certificate into the HTML Server to validate OAuth 2.0 token locally in the HTML Server. For more information, see "Adding an Existing Certificate to a New Keystore" in the JD Edwards EnterpriseOne Tools Security Administration Guide.

  6. The EnterpriseOne HTML Server returns the authorization response to the AIS Server. The PS Token is included in the response.

  7. The AIS Server returns the authorization response to the AIS client (third-party). If passed, for a token request the response includes an AIS token.

    In stateless scenario, if passed, the actual resources are provided to the user.

4.3.1 Creating an OAuth 2.0 Resource Server

If you have an EnterpriseOne configuration through Oracle Access Manager (OAM), then you can follow the following steps to set up an OAuth 2.0 resource server with OAM:

  1. Log in to the Oracle Access Management console.

    The Launch Pad opens.

  2. Click Mobile OAuth Services.

  3. Select the default domain or create a domain.

  4. Click the Resource Servers tab.

  5. On the Custom Resource Server Configuration page, complete the following fields:

    Name

    The name of this resource server (or resource service).

    Description

    (Optional) A short description to help you or another administrator identify this resource server in the future.

    Allow Token Attributes Retrieval

    Select this option to allow custom attributes (both attribute names and values) to be shared with clients and the resource owner.

    For more information, see "Configuring OAuth Service Profiles" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management for All Platforms.

    Authorization & Consent Service Plug-in

    From the menu, choose an authorization plug-in for the resource server. This plug-in type defines security policy around interactions where authorization and user consent are granted. It can influence claims in a generated token as well.

    Resource Server ID

    The unique ID created for this resource server during registration.

    Scope

    Click Add to add a new row to the scopes table.

    Note:

    JD Edwards EnterpriseOne supports only single scope and all orchestrations are validated for single scope.
    Name

    Type a scope definition. Use dot notation, for example: photo.read.

    Description

    Type a short note that describes the scope.

    For more information, see "Understanding the OAuth Resource Servers Configuration Page" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management for All Platforms.

  6. Click Save.

4.3.2 Creating an OAuth 2.0 Client

Complete the following steps to create an OAuth 2.0 client:

  1. Log in to the Oracle Access Management console.

    The Launch Pad opens.

  2. Click Mobile OAuth Services.

    The OAuth Identity Domains page opens.

  3. Select the default domain or create a domain.

  4. Click the OAuth Clients tab.

  5. To create an OAuth Web client, click the Create button located directly under the OAuth Web Clients heading and complete the following fields:

    Name

    The name of this OAuth client.

    Description

    (Optional) A short description to help you or another administrator identify this OAuth Web client in the future.

    Client ID

    The unique ID that the authorization server created for this client during registration. The client ID must be a valid JD Edwards EnterpriseOne user.

    Allow Token Attributes Retrieval

    Select this option to allow custom attributes (both attribute names and values) to be shared with resource servers and the resource owner.

    Client Secret

    A secret value known to the OAuth authorization service and the client. The authorization service checks the client secret and the client ID when it receives token endpoint requests from the client.

    Privileges
    Bypass User Consent

    If selected, the client will not ask for the user's explicit authorization to access the user's protected resources.

    This option must be selected for the OAuth 2.0 to work as JD Edwards EnterpriseOne supports only two legged OAuth authentication for AIS services and orchestrations.

    Allowed Scopes

    Lists the range of access the client has to the requested resources. To grant additional access, click Add to add a row to the table, then choose from the drop-down menu the scope to be added.

    Grant Types
    Client Credentials

    The client requests an access token using only its client credentials.

    For more information, see "Understanding the OAuth Web Clients Configuration Page" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management for All Platforms.

  6. Click Save.

4.4 Configuring OAuth 2.0 Resource Servers with OAM 12c

You can use an OAuth 2.0 resource server to handle the authentication requests from AIS clients. This type of authentication allows access to AIS services, as well as orchestrations created using the Orchestration Studio. In this authentication process, an OAuth token is requested from an authentication provider and then passed to the AIS token request (stateful) or AIS service directly (stateless). If the AIS token request (stateful) is used, the AIS token is used for subsequent AIS calls.

To use OAuth 2.0, the format of the OAuth 2.0 token must be JWT and you must configure the steps required for JWT configuration.

See "Configuring EnterpriseOne HTML Server for JSON Web Token (JWT) (Release 9.2.3.2)" or "Configuring EnterpriseOne HTML Server for JSON Web Token (JWT) (Release 9.2.0.5)" in the JD Edwards EnterpriseOne Tools Security Administration Guide.

The following steps describe the configuration and authentication flow:

  1. Create an OAuth 2.0 resources.

    See Section 4.4.1, "Creating an OAuth 2.0 Identity Domain" for more information.

    SeeSection 4.4.2, "Creating an OAuth 2.0 Resource Server" for more information.

    See Section 4.4.3, "Creating an OAuth 2.0 Client" for more information.

    See Section 4.4.4, "Fetching Identity Domain Certificate" for more information.

  2. Get an OAuth 2.0 token using the registered client ID, secret, domain, and scope.

    The following is an example of the parameters that you would provide to generate an OAuth 2.0 token. In this example, the value passed for Authorization parameter 'SkRFOnBsNEhBYzg5' is a base64 encoded value of client ID and secret that is separated by a colon.

    curl -i -H 'Authorization: Basic <SkRFOnBsNEhBYzg5'> -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -H "X-OAUTH-IDENTITY-DOMAIN-MAME:<JDEIdentityDomain>" --request POST http://mycompany.com:14100/oauth2/rest/token -d 'grant_type=client_credentials&scope=<JDEResourceServer>'.

    Parameter Value Description
    Authorization Header Basic <base34_clientid_secret> This parameter contains base64 encoded values of the client ID and client secret separated by colon. The parameter is used as access token by the client.
    Client ID <client_id> This parameter is the unique API key that is generated when you register your application with OAM.
    Client Secret <client_secret> This parameter is the private key that is generated when you register your application with OAM.
    Access Token URL /oauth2/rest/token This parameter is an endpoint that is used to obtain an access token from OAM.
    Grant Type client_credentials This parameter indicates that the REST API to be invoked is owned by the client application.
    Scope JDEResourceServer This parameter returns all the grants provided to your application.
    Domain JDEIdentityDomain This parameter is the Identity Domain name under which all clients and resource servers are created.

  3. An OAuth 2.0 token is generated with the client ID, secret, and scope and sent in the Bearer header of an AIS token request. (Stateless requests are also supported.)

  4. The AIS Server forwards the OAuth 2.0 token to the EnterpriseOne HTML Server and is configured to allow a JWT. The AIS Server forwards the OAuth 2.0 token in the Bearer if login is required.

  5. The Security Server checks the PS Token with node trust, and returns an authorization response to the EnterpriseOne HTML Server. You must import the OAM certificate into the HTML Server to validate OAuth 2.0 token locally in the HTML Server. For more information, see "Adding an Existing Certificate to a New Keystore" in the JD Edwards EnterpriseOne Tools Security Administration Guide.

  6. The EnterpriseOne HTML Server returns the authorization response to the AIS Server. The PS Token is included in the response.

  7. The AIS Server returns the authorization response to the AIS client (third-party). If passed, for a token request the response includes an AIS token.

    In stateless scenario, if passed, the actual resources are provided to the user.

Note:

Before you create resources, you need to enable OAuth and OpenIDConnect Service from the OAM admin console. You can enable OAuth service from the Configuration tab under Available Services in the OAM console. If OpenIDConnect Service is not available in OAM, install the latest available bundle patch for OAM 12c.

4.4.1 Creating an OAuth 2.0 Identity Domain

An identity domain corresponds to the notion of a tenant. All clients and resource servers are created under an identity domain. If you have an EnterpriseOne configuration through Oracle Access Manager (OAM 12c), follow these steps stated in the Administrating Oracle Access Management to create the identity domain with OAM 12c - Creating an Identity Domain.

4.4.2 Creating an OAuth 2.0 Resource Server

If you have an EnterpriseOne configuration through Oracle Access Manager (OAM), then you can follow these steps stated in the Administrating Oracle Access Management to set up an OAuth 2.0 resource server with OAM - Creating a Resource.

4.4.3 Creating an OAuth 2.0 Client

Follow these steps stated in the Administrating Oracle Access Management to create an OAuth 2.0 client - Creating a Client.

4.4.4 Fetching Identity Domain Certificate

You need to fetch identity domain certificate when the domain is created. This is done using REST API:

  1. http://{{host}}:{{mgdport}}/oauth2/rest/security?identityDomainName={{domainname}}

  2. Extract the content from JSON response against the key 'x5c'.

    1. Create cert files with 2 signing keys.

    2. Create cert file for each certificate part from above response by placing it between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

    3. Save these files.

    Note:

    Ensure that there are no extra spaces in the files to import successfully.