Hitachi

JP1 Version 12 JP1/Integrated Management 2 - Manager Command, Definition File and API Reference


5.2.8 Authentication methods for REST API

In order for users to issue API requests and get responses, they must be authenticated first. The following types of authentication are available on the Intelligent Integrated Management Base:

Organization of this subsection

(1) Authentication by using the login API

The following describes steps for authentication with the login API.

  1. Invoke the login API.

    Provide the JP1 user name and password to be authenticated and then, if successful, receive the token string and cookie string. For details on the login API, see 5.4.1 Login.

  2. Invoke a REST API.

    To invoke a REST API, set the following HTTP request header with the token string that was retrieved by the login API.

    You can invoke the REST APIs other than login and logout.

    Request header

    Authorization

    Value to be specified

    Bearer token-string

    Example of a specification

    For example, if the token string anAxYWRtaW46TUdGa01tTTJNMlV3TURFNFh6STNYekE0T2p is obtained by the login API, specify as follows:

    Authorization: Bearer anAxYWRtaW46TUdGa01tTTJNMlV3TURFNFh6STNYekE0T2p
  3. Invoke the logout API.

    Use the cookie string that was retrieved by the login API to discard the authentication information that is used for the current login. For details on the logout API, see 5.4.2 Logout.

(2) Authentication through login information added to a REST API (Basic authentication)

The following shows the procedure for Basic authentication through login information added to a REST API.

By default, the Basic authentication setting is disabled. To enable it, set the jp1.imdd.authBasic property to true in the Intelligent Integrated Management Base definition file (imdd.properties).

For details on the Intelligent Integrated Management Base definition file (imdd.properties), see Intelligent Integrated Management Base definition file (imdd.properties) in Chapter 2. Definition Files.

  1. Invoke a given REST API.

    In the HTTP request header on invocation of a REST API, specify Basic as the authentication method, followed by a Base64-encoded string of the user name concatenated with the password using : (ASCII: 0x3A) (which is called a basic token).

    Request header

    Authorization

    Value to be specified

    "Basic " + Base64-encoded ASCII string of JP1-user-name:password

    Example of a specification

    If the JP1 user is jp1user and the password is password, then use the Base64-encoded string of jp1user:password, anAxdXNlcjpwYXNzd29yZA==, to specify the basic token as shown below:

    Authorization: Basic anAxdXNlcjpwYXNzd29yZA==

Important
  • Do not specify any cookie in the request header because Basic authentication is a stateless authentication method.

  • Basic authentication can be used with either of HTTP or HTTPS, but we recommend access over HTTPS for better security.

  • The authentication server performs authentication every time a REST API is executed, and therefore each authentication operation outputs a message related to the user management function to the server. If the authentication server also has a system that outputs integrated trace logs, design the system configuration with the possibility that the messages related to the user management function may cause a high load on the integrated trace in mind.

(3) Authentication through login information added to a REST API (OpenID authentication)

The following shows a procedure for OpenID authentication by using login information added to a REST API.

OpenID authentication is disabled by default. To enable it, you have to edit the OpenID provider-related properties provided in the Intelligent Integrated Management Base definition file (imdd.properties).

For details on the Intelligent Integrated Management Base definition file (imdd.properties), see Intelligent Integrated Management Base definition file (imdd.properties) in Chapter 2. Definition Files.

  1. Invoke a REST API.

    In the HTTP request header for invoking a REST API, specify Bearer as the authentication method, and then the access token submitted by the OpenID provider.

    Request header

    Authorization

    Value to be specified

    Bearer string-representing-access-token

    • When multiple OpenID providers are set as the authentication infrastructures on the Intelligent Integrated Management Base, you must specify the key name (access token issuer) of the OpenID provider in the HTTP request header X-Token-Issuer that is used to invoke a REST API. The key name that you specify here must be the one that is defined in the Intelligent Integrated Management Base definition file (imdd.properties).

    • If, upon the acceptance of the processing of the REST API by the Intelligent Integrated Management Base, it turns out that the HTTP request header X-Token-Issuer is not specified or that the value specified for X-Token-Issuer does not match the OpenID provider's key name defined in the Intelligent Integrated Management Base definition file (imdd.properties), an authentication error occurs. In this case, the status code 403 and the error message KAJY52030-E are returned to the caller of the REST API.

    • When only one OpenID provider is set as the authentication infrastructure on the Intelligent Integrated Management Base, you do not have to specify the HTTP request header X-Token-Issuer that is used to invoke a REST API. When this HTTP request header is not specified, the Intelligent Integrated Management Base processes the REST API assuming that the OpenID provider defined in the Intelligent Integrated Management Base definition file (imdd.properties) is the access token issuer.

    • X-Token-Issuer is a unique request header defined in the Intelligent Integrated Management Base, which has the following format:

      Request header

      Value to be specified

      X-Token-Issuer

      Name of the OpenID provider that issued the access token.

      Specify the value representing the OpenID provider's key name defined in the Intelligent Integrated Management Base definition file (imdd.properties).

    Example 1

    - The access token is issued by Keycloak.

    - Only one OpenID provider is set as the authentication infrastructure on the Intelligent Integrated Management Base definition file.

    The key name of the OpenID provider (Keycloak)

    - The access token submitted by the OpenID provider is ABCDEFG.HIJKLMN.OPQRSTUVWXYZ.

    Under the conditions described above, set the access token in the request header as follows:

    Authorization: Bearer ABCDEFG.HIJKLMN.OPQRSTUVWXYZ

    Example 2

    - The access token is issued by Keycloak.

    - Multiple OpenID providers (Keycloak and Okta) are set as the authentication infrastructures on the Intelligent Integrated Management Base.

    The key name of one OpenID provider (Keycloak)

    The key name of the other OpenID provider (Okta)

    - The access token submitted by the OpenID provider is ABCDEFG.HIJKLMN.OPQRSTUVWXYZ.

    Under the conditions described above, set the access token and the token issuer in the request headers as follows:

    Authorization: Bearer ABCDEFG.HIJKLMN.OPQRSTUVWXYZ

    X-Token-Issuer: Keycloak

Important
  • Although HTTP and HTTPS are both supported, we strongly recommend the use of HTTPS for OpenID authentication to protect against man-in-the-middle attacks. During operation, make sure to use HTTPS for access.

  • In order to allow the JP1 user name used with the Intelligent Integrated Management Base to be mapped with the user name registered with the OpenID provider, the preferred_username claim of the access token must contain the name of the user logging in to the Open ID provider. When Keycloak is the issuer of the access token, the preferred_username claim is set in the access token by default. When Okta is the issuer of the access token, you must manually set the preferred_username claim. For details on how to set the preferred_username claim, see the document supplied by Okta.

    When the preferred_username claim is not set, the error message KAJY52028-E is returned. For details on the single sign-on mapping definition, see Single sign-on mapping definition file (imdd_sso_mapping.properties) in Chapter 2. Definition Files.