Basic Concepts for Integration

The following sections describe the basic concepts of the integration solution.

Tenants

Once you are onboarded to the HID Authentication Service, you will receive a logon credentials for the Administration Portal for your tenant.

Each tenant is a completely independent, isolated environment in the HID Authentication Service.

You can see your Tenant ID from the Tenant Info menu item. The Tenant ID has the following format:

't' + alpha numeric random identifier

For example, t17b5e9c64237164237900

The ID is a logical link to your environment in the HID Authentication Service, including:

• Your data store

• Your encryption keys

This ID is required to leverage the HID Authentication Service and the OpenID and SCIM APIs.

OpenID and SCIM APIs

OpenID and SCIM APIs are the main interfaces to leverage the HID Authentication Service. These APIs comply with public standards and provide the following benefits:

• They are well-defined industry standards for authentication and user management, easing the integration effort

• They are REST based APIs, which makes them portable and able to integrate with any client technology (Java, C#, C, JavaScript, Python ...), including mobile apps

For further information, see SCIM standards and OpenID standards.

To view the complete HID Authentication Service API reference documentation, see SCIM Reference and OpenID Reference.

Client IDs

The authentication mechanism with OpenID is a two-step process. When the HID Authentication Service handles an OpenID authentication request, it not only identifies the real human being (the end user), but also identifies what the user is using to authenticate with, the application (the Client ID).

The end user is indeed not the one who is authorized to use OpenID (the end user will not write a REST request to the HID Authentication Service), it is the application (your application) through its Client ID that allows the user to authenticate.

A Client ID is a unique user in your tenant, specially configured (with a group, a role and a set of registration data) to be authorized through OpenID.

A Client ID represents a resource or an application, that is, an actual client of the HID Authentication Service APIs:

It is important that each of your applications have a distinct Client ID. This will allow you to differentiate the different applications in your Audit log. It also allows you to have specific configurations and policies for each of your applications.

For further information about Audit logs, see Monitoring my Tenant - Audit Logs and Records.

Let's take the example of a Bank. We can imagine two distinct applications:

• Bank web site

• Bank mobile application

Each one of those applications may have different requirements in terms of authentication, and the Bank administrators want to distinguish them in the Audit logs. Therefore, 2 Client IDs are created - clientid-web and clientid-mobile.

The Client ID is thus a user, with an internal ID as well as an external ID. However, the Client ID also holds a set of configuration data that allows the authentication to take place:

• The authentication channel

• The authentication policies to be used for the Client ID and the end user

For further information about Client ID configuration, see Register a Client ID (or a Client ID for M2M).

End Users

While a Client ID represents an application, we call end users the actual human beings that are identified and authenticated with the HID Authentication Service OpenID API.

• In the context of an authentication, the client ID is the direct user, and the end user is the indirect user.

• In the specific context of M2M architectures and OpenID client_credentials flow, only the client ID is involved in the authentication. Indeed, there is no human being involved. The client ID is then the only direct user.

Internal IDs vs External IDs

While using the HID Authentication Service APIs, you deal with internal IDs and external IDs.

• An internal ID is a unique number, generated by the HID Authentication Service and immutable, that identifies a resource within your tenant (Users, Client IDs).

  For example, 76532. The internal ID is an identifier that you must use with SCIM APIs to update/delete users and Client IDs.

• An external ID (the externalId parameter) is a unique alpha-numeric identifier that you give to your users and Client IDs upon creation.

  For example, user-9876876123 or user@company.com. The HID Authentication Service will enforce their uniqueness through the API endpoints.

  The externalId is the identifier that the HID Authentication Service will use to authenticate your user (the login string the end users must provide along with their credentials to authenticate).

It is up to you to decide which kind of data you want to use as user's login (external IDs). The only constraint is the uniqueness, therefore the HID Authentication Service recommends to choose a unique consistent identifier within your application, such as:

• Corporate email address

• Corporate unique identifier

• Patient identifier

• ...

For further information on how internal and external IDs are used in the authentication flow, see Managing User or Client ID Authenticators and Managing Users, Groups and Roles.

Devices and Credentials

The HID Authentication Service supports device-based authentication factors (One-Time Password, Mobile Push-based ...).

Whether it is an OTP (One-Time password) on a physical device, a PKI (certificate-based) or any other device-based factor, the HID Authentication Service maps a Credential and a Device that are associated to an End user.

The Device holds information such as the serial number of the actual physical device, while the Credential holds the secret, such as transaction keys for HID Approve or synchronization seeds for OTP devices.

Examples of devices:

• HID Approve smartphone app (Push-based authentication)

• An HID OTP Device
  

For further information about devices and credentials in the authentication flow, see Managing Devices and Credentials.

Authentication Policies

Authentication Policies define authentication factors settings, such as password lengths or constraints, OTP synchronization protocols, push notification signature details...

The HID Authentication Service supports the following authentication policies:

• What you know
  

  • Password

• What you have
  

  • One-time password devices (virtual or physical)

  • Out of band (code via SMS or Email)

  • Push-based validation with the HID Approve application

  • PKI certificate

The HID Authentication Service includes a set of policies that are available out of the box (see the following sections).

Authentication Policies for Client IDs

As a Client ID is an application, and by extension a machine, only two policies are available.

Code	Description	Authentication Policy	Type of factor	Level of protection
AT_SYSLOG	Client ID password policy	Password	What you know	LOW
AT_JWT	Client ID PKI-based JSON Web Tokens	PKI (certificate)	What you have	STRONG

Authentication Policies For End Users

Code	Description	Authentication Policy	Type of factor	Level of protection
AT_STDPWD	Standard Password	Password	What you know	LOW
AT_RESPWD	Restricted Password (the policy is more demanding than with standard password)	Password	What you know	LOW
AT_OOB	Out of Band SMS or Email	Out of Band	What you have	AVERAGE
AT_OTP	One-Time Passwords, for virtual or physical devices	One Time Password	What you have	STRONG
AT_TDS, AT_PASA, AT_SMK	HID Approve Push Notifications and signed Transactions	Signed Transactions	What you have	STRONG

Examples of Multi-Factor authentication for End Users

Combining authentication policies is the best way to achieve strong protection of resources.

Code	Description	Type of factor	Level of protection
AT_STDPWD, AT_RESPWD + AT_OOB	Password (standard or restricted) + Out of Band Email or SMS	What you know + what you have	STRONG
AT_STDPWD, AT_RESPWD + AT_OTP	Password (standard or restricted) + One-Time Passwords, virtual or physical devices	What you know + what you have	OPTIMAL
AT_STDPWD, AT_RESPWD + AT_PASA	Password (standard or restricted) + HID Approve Push notification	What you know + what you have	OPTIMAL

Channels

The channel is a concept that allows to segregate authentications made with the HID Authentication Service. It can be seen as a virtual pipe in which the HID Authentication Service processes an authentication request.

The HID Authentication Service defines only one channel, CH_EXTRAPP, for external applications.

The HID Authentication Service needs to know the channel to authenticate a user, this is enforced by the configuration of the client ID, that holds the channel to be used.

Authenticators

The Authenticator is a central concept required for authentication. To create an authenticator for an end user or a Client ID, you need to indicate an authentication policy (and a device if it is a device-based authentication policy). It can be seen as an instantiation of an authentication policy for a given user.

A user can have as many authenticators as there are authentication policies in the HID Authentication Service. However, a user can have only one authenticator per authentication policy.

Without authenticators, a user or a Client ID cannot authenticate to the HID Authentication Service.

For example, the user John Smith that has the following authenticators:

• AT_STDPWD - a standard password authenticator. No device is associated to this kind of authenticator. The authenticator holds the encrypted password.

• AT_OOB an SMS out of band authenticator. No device is associated to this kind of authenticator. The authenticator holds the secret used to generate codes. The phone number associated with the user is used to send SMS messages.

• AT_OTP - an OTP authenticator. The user owns and is assigned an physical OTP device in the HID Authentication Service (where the authenticator is mapped with the serial number of the device). The device is linked to a Credential containing the secret seed for the OTP device, allowing the HID Authentication Service,to validate OTPs.

You cannot create a new AT_STDPWD authenticator for John Smith as he already has one of that kind defined. However, you can add AT_TDS, AT_PASA, AT_SMK authenticators to enable Push, or even an AT_RESPWD authenticator for a second password, with more demanding constraints.

The authenticator also contains the statistics of authentication for the user, such as the number of successful/failed authentications.

Tokens

A token (or bearer token) is an object that contains the security context of an authentication in the HID Authentication Service.

A token contains information about the user, their privileges, their group and roles, and the authenticator used for the authentication. A token allows you to "prove" that a user is authenticated against the HID Authentication Service. A token has a lifetime and thus expires. It is comparable to the principle of web sessions.

The token is thus a proof of an identity as well as a credential to access the HID Authentication ServiceAPIs.

A Web Token (and more particularly a JSON Web token - JWT - often pronounced "jot") is a token that is suitable for web / REST API usage. It is a Base64 URL, encoded for safe transfer over HTTP. They follow the JWT standard JWT standard.

The HID Authentication Service supports the following types of tokens:

• Access tokens - the most common way to prove an identity, as well as the easiest to use. You can see it as a session identifier. It does not contain any readable data for you. However, you can use it with any the HID Authentication Service API endpoint to be granted access to it (depending of course on the roles of your user). Access tokens are part of the OAuth2 standard: https://tools.ietf.org/html/rfc6749#section-1.4.

  In the singular case of federated authentications, the Access Token is an ID Token.

  Copy

  {"access_token":"FnMOZwAAAWupkj2WCQzBvB35NDoIMAecsCdq4FLD","token_type":"Bearer","expires_in":3600}

• ID Tokens: - always a JWT and is comparable to an access token, but holds JSON readable information about the user and the Client ID. It is also signed, which allows you to validate the identity of the owner as well as the Identity Provider (the HID Authentication Service). ID tokens can also be encrypted using a certificate attached to the OpenID client ID.

  It is a Base64 URL-encoded JSON-formatted piece of data. It is split into three parts - the header, the body and the signature. It is described in the OpenID Core standard https://openid.net/specs/openid-connect-core-1_0.html#IDToken.

  Copy

  eyJraWQiOiIxNTM2ODU0OTk4MTA3IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJqb2huLnNtaXRoQGdtYWlsLmNvbSIsImVtYWlsX3ZlcmlmaWV
  kIjpmYWxzZSwiZ3JvdXBpZHMiOlsiVUdfUk9PVCJdLCJyb2xlcyI6W10sInBob25lX251bWJlcl92ZXJpZmllZCI6ZmFsc2UsInBob25lX251bWJlciI6I
  jg3NiA1NjcgNDU2IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiam9obi5zbWl0aEBnbWFpbC5jb20iLCJlbWFpbCI6ImpvaG4uc21pdGhAZ21haWwuY29tIn0. KZ24TGBszK-Cx3jpseuNKO6TZN0x-uIUwxNYRVb5Rba5pMmSV4cVNXsx6SKDIlTUnVwJpF1pZKTkEqHhtCIjCFPB2djE0ytMdeU5PBRPIbYYp1YL78A1cVRTDM7uNpbnULSZifCQv8ha7bRNLfiwQGinh8oAJCzFMJRSnbR2r
  JSw48PubpJvIs4dVtfDY1cF1aGBHQlEr2k60pYtBref7mUkTHbOX9c4k9KDMgV02gEJbhzVVEP33BD_OWsJdw_aaouC6Zko5qYYtBr1m6om93gMlt4MB_MLPMccmRjJAyUeFuesCvge9NWfdopU2RmYcn2bRaKoS6Iy4USzFUXiJg.

  Copy

  Header

  {
      "kid": "1536854998107",
      "alg": "RS256"
  }

  Copy

  Body

  {
      "sub": "john.smith@company.com",
      "email_verified": false,
      "groupids": ["UG_ROOT"],
      "roles": ["RL_ORGADMIN"],
      "phone_number_verified": false,
      "phone_number": "876 567 456",
      "preferred_username": "john.smith@company.com",
      "email": "john.smith@company.com"
  }

  Copy

  Signature

  KZ24TGBszK-Cx3jpseuNKO6TZN0x-uIUwxNYRVb5Rba5pMmSV4cVNXsx6SKDIlTUnVwJpF1pZKTkEqHhtCIjCFPB2djE0ytMdeU5PBRPIbYYp1YL
  78A1cVRTDM7uNpbnULSZifCQv8ha7bRNLfiwQGinh8oAJCzFMJRSnbR2rJSw48PubpJvIs4dVtfDY1cF1aGBHQlEr2k60pYtBre
  f7mUkTHbOX9c4k9KDMgV02gEJbhzVVEP33BD_OWsJdw_aaouC6Zko5qYYtBr1m6om93gMlt4MB_MLPMccmRjJAyUeFuesCvge9NWfdopU2RmYcn2bRaKoS6Iy4USzFUXiJg 

• Refresh Tokens - a refresh token can be obtained while getting an access token (in the same request). It is a specific token that allows your application to fetch a new access token (upon expiration of the previous one) without prompting the end user for their credentials. You can thus "refresh" your access token. Refresh tokens are part of the OAuth2 standard https://tools.ietf.org/html/rfc6749#section-6.

The Authentication Portal and IdP

The HID Authentication Service includes a ready to use, out of the box featured login portal that allows you to easily leverage all of the different authentication factors that our service offers.

You can redirect your end users to the portal and let HID Authentication Service handle the enrollment and authentication process.

The HID Authentication Service then redirects the user back to your application with an authentication response.

For further information, see Configuring the Identity Provider.

For guidance about leveraging the portal, contact HID Global Technical Support.

HTTPS Methods

The HTTPS methods used in the APIs are:

Method	Usage
GET	Retrieves one or more complete or partial resources.
POST	Depending on the endpoint, creates new resources, performs a search request.
PUT	Modifies a resource by replacing existing attributes with a specified set of replacement attributes (replace). Do not use PUT to create new resources.
DELETE	Deletes a resource.