iPIM Server REST API Authentication

iPIM Server provides two different approaches to handle authentication against it's REST API: iPIM-* Headers and OAuth 2.0 authentication.

iPIM-* Headers

iPIM REST API uses the following headers to submit the user credentials and client selection:

iPIM-User: ipim-web
iPIM-Pass: secret
iPIM-ClientId: 1
iPIM-ClientLevelId: 1
iPIM-ExportResponseObjects: true (optional, default: true)
  • iPIM-ClientLevelId describes the context level (e.g. for the maintenance of attribute values in special contexts/layers)
  • iPIM-ExportResponseObjects triggers the export of changed objects when modifying data via PUT/POST/PATCH

OAuth 2.0

iPIM 4.4.04 introduced the first implementation of a fully integrated OAuth 2.0 authorization & resource server in iPIM Server as the central authorization server.

For more details about OAuth 2.0, check out this reference OAuth 2 Simplified

The following RFCs which describe the OAuth2 framework with several extensions have been (partially) implemented:

Login & Authorization Code Flow

The following sequence diagram shows a user trying to access iPIM Portal. Since iPIM Portal has no active session for the user, they are redirected to iPIM's login page. On successful authentication, the user is redirected back to iPIM Portal with a short-lived authorization code encoded in the redirection URL. iPIM Portal uses the authorization code to request valid access and refresh tokens:

oauth2-authorization-code-flow

Client Configuration

To access iPIM's REST API as a client a corresponding API user should be created:

nickname: <client name>
password: <client secret>
apiuser: true

The following user AVs are available to configure the login page and secure the user's login flow:

  • OAUTH2_APPLICATION_NAME name of the client app, will be displayed in the login page
  • OAUTH2_BACKGROUND fully qualified URL to a background image that will be displayed in the login page
  • OAUTH2_REDIRECTION_URI fully qualified URI that will be used to redirect the user after successful login

The client itself should use the following settings:

  • Authorization URL: <iPIM-Server>/iPIM/authorize
  • Access token URL: <iPIM-Server>/iPIM/rest/api/oauth2/token
  • Client ID: <client name>, like "ipim-web"
  • Client secret: <client secret>, token of the API user
  • Redirection URL: must match OAUTH2_REDIRECTION_URI, if the user AV is configured
  • Scope: client:<iPIM client>, available permissions are:
    • ipim-core.api
    • ipim-supply.api:read, ipim-supply.api:write
    • ipim-web.api:read, ipim-web.api:write

Authorization Server Configuration

iPIM uses JWS (signed JWTs) for it's access and refresh tokens to make the authentication mostly stateless. JWS require a private/public key pair which will be used to sign and verify the generated tokens; both in the authorization server but also by OAuth clients and resource servers (iPIM Supply, iPIM Web).

By default, iPIM generates a new key pair on every start. This invalidates all existing tokens immediately, since they can not be verified against the new key.

A keystore or PEM file can be configured to provide persistent private/public key pairs, that generate tokens which will survice a restart of the application server.

  • Configure KeyStore
    Create a new keystore containing at least one key. Both the key and the keystore itself can be password protected.
    Add the keystore to the EAR file or deploy it directly on the server:

    // in build.gradle, to deploy within the EAR
serverJar.into("META-INF") {
  from("conf/jwk")
}

    Configure iPIM to load the keystore, configure the primary key that should be used to sign the generated tokens and provide the required credentials:

    oauth2.authentication-server.jwk.type=keystore
oauth2.authentication-server.jwk.id=<key-name>
oauth2.authentication-server.jwk.keystore.path=<path/to/keystore.jsk>
oauth2.authentication-server.jwk.keystore.password=<keystore-password>
oauth2.authentication-server.jwk.keystore.key.<key-name>.password=<key-password></key-password>

    During start up, iPIM will try to load and open the keystore and register the provided key to support signing tokens.

  • Configure PEM File

    oauth2.authentication-server.jwk.type=pem
oauth2.authentication-server.jwk.pem.path=<path/to/file.pem>