Corporate Identity users need to be authenticated before they can access or operate on a Corporate Identity or a related instance. This can be done through an Authentication Service that validates the authentication secret and signs the subject information for a chain of correlated service calls. This service assumes that the credential being authenticated already exists. Refer to the Auth and Passwords Swagger documentation for the complete list of APIs that may be invoked in relation to authentication.

API methods for Authentication:

URL Method Description
/auth/login POST This operation will authenticate and logon the identified credential for an authenticated session. An authentication token that may be used for subsequent calls that require authentication is returned.
/passwords/profiles/{identity_profile_id}/get POST Retrieve the details of the Password Profile supplied in the request.
/passwords/identities/{identity_id}/get POST Returns the Profile ID linked with the identity.
/passwords/{credential_id}/create POST Create a new password for the credential identified by the credential_id path parameter.
/passwords/{credential_id}/get POST Returns information about the password, such as its version, who owns it, and the expiry. The actual password value is not included in the response.
/passwords/{credential_id}/update POST Update the password for the given credential ID. The password version will be incremented. Once is has been updated it can no longer be used to login.
/passwords/{credential_id}/{version}/expire POST Expire the password instance using the version specified in the request.
/passwords/{credential_id}/authenticated_update POST Allows password updates for authenticated users without requiring the old password to be submitted.

Other Information:

  • You will need to use a password profile to create an instance of a password. You can use an existing password profile.

  • An identity profile must exist before being able to create a password profile. The password profile must be created using the same ID as that of the identity profile. In this way, the password profile may be viewed as an extension of the identity profile. This password profile will be used to create and update of passwords belonging to credentials linked to an identity that has been created from this extended identity profile.

  • An authenticated session allows a credential to call secured operations which require identification (the session is independent of the secret type used to create it). At logon, a session is created, represented by a token. This key is used to perform all operations as the authenticated credential.

    A session can be terminated due to:

    • Logout – the user explicitly logs out

    • Forced by Admin – the session was terminated by the system e.g. because an account has been disabled.

  • Edge services may cache a conversion table between an external session identifier and the internal session token. E.g. If supporting HTTP Basic Authentication in an application, it is advised to create a session once for the credential, and then map the username and password combination to a session token internally so to avoid unnecessary authentication calls.

  • Subject: The term ‘subject’ in this context refers to an authenticated credential, together with all the identification information.

  • Shared Secret: A shared secret represents a piece of information that is shared between the authenticating system (OPC) and the identity credential. This shared secret is a means of authentication that the credential uses to verify itself. The most common type of shared secret is a password.

  • Password: The password secret authentication service is provided due to its widespread use. Validating a password secret involves verifying that it matches against the latest, non-expired password created for a credential. For security, this string is stored in the database using a key derivation function (typically based on a hashing algorithm), to protect passwords against common attacks and theft of exposed confidential secret information due to a security breach.

    The password secret involves implementation of:

    • Create – Linking a provided password with the credential (storing only the hashed version)

    • Reset – This replaces the current password with a new one, if the provided current password is valid (compared to the one stored on the database).

    • Expire – A password version can be expired (although when the latest password is updated it would automatically be expired).