Authentication

Authentication

Access to the API requires authentication as a registered user. The privileges and access granted will be commensurate with the authenticated user. An authentication endpoint will return an authentication token which is a JSON Web Token (JWT).

The API is:

   POST /auth/login

With a body including the Email address and Password of the account assuming a non-SSO, local account. SSO authentication will be described in an updated version of this document. An example body would be:

{
“email”: “somebody@localhost”,
“password”: “ThisIsAPrettySecureP@ssw0rd!”
}

Assuming a successful response with an HTTP 200 (Success) result, a JSON object is returned including:

• token – The JWT token to be used in subsequent API calls
• email – The email address of the logged in user
• id – The internal BE ID of the logged in user

The JWT token, documented in RFC-7519, decodes to include the user id, email, username as well as orig_iat (Original Issued-At time) and exp (Expiration) values to indicate when the token originated and expires.

Unsuccessful attempts would return an HTTP 400 (Bad Request) result. The error would follow standard error returns described below.

Authentication: Token Refresh

At any time before the expiration, a token can be refreshed without the original credentials. There is an overall expiration after which re-authentication is required for security, but this allows the core authentication tokens to expire more frequently provided the application periodically refreshes them.

The API to refresh a token is:

POST /auth/refresh

This is a JSON request and the body must include:

{
“token”: The token received either login or refresh
}

Assuming a successful response (HTTP 200), you will receive a JSON body including the updated token value. Use that value in subsequent API calls.

Authentication Service

Prism allows an Account Admin account to register an Authentication Service. This is intended to configure OpenID Connect services supporting Single Sign On (SSO) for your users. Each service has a unique name. This name can be used in the login to bypass Prism user selection and go straight to SSO. The URL for such a bypass uses the name as follows:

https://connect.buildingengines.com/sso_provider?service=name

The Authentication Services optionally allow Authorization Settings. If enabled, these settings will look for a specific claim from the successful login and map it to a regular expression to identify the Job Function and Permission Groups the user should have. In this way, authentication and authorization can be driven by SSO.

NOTE: The following parameters assume some knowledge of OpenID Connect.

   POST /auth/sso_authentication_service

This call will create a new Authentication Service entry. The payload of the request most importantly contains the Authentication Service name which will be used in subsequent requests.

Below is the parameter. A number of these are optional depending on the requirements of the integration. Included are the parameters, in JSON format, include:

• name – Unique identifier, maximum of 15 characters (example: “excorp”)
• provider_type – Type of provider; must be “oidc” (OpenID Connect) or “office365”
• redirect_uri – Redirection URL; typically should be

https://connect.buildingengines.com/auth/{{name}}/sso_callback_oidc

• issuer – Issuer URL
• response_type – should be “code”
• client_id – String with client identification from provider
• client_secret – (Optional) String with client secret information from provider is applicable
• audience – (Optional) Identification string
• openid_configuration_url – (Optional) URL with well-known OpenID Connect configuration return
• email_claim – String, max length of 20, where the parameter in the token identifying the email address of the authenticated user. The default is “unique_name”.

In addition to the above parameters, two special parameters accept JSON objects. These are:

• additional_request_arguments

This accepts a dictionary of name/value pairs as strings. Each of these will be added to the request claims made to the provider. This allows further customization particularly when authorization options are used as well.

• authorization_settings
  This parameter accepts a specially formatted block that allows regular expressions to map a given returned claim to the permissions a user should have. The format of the JSON object includes is a dictionary with two entries role_claim – this is a string with the name of the role claim from the authentication response and roles – this is an array of objects.

Within each record in the roles array include three keys:

pattern – This is a regular expression and the first match will be used to set the users authorization. As an example, “^READER.*-DEV$” would match “READER-1234-DEV”.

job_function_id – This ID should correspond to a Job Function by GUID as described elsewhere in the section related to Permissions

permission_group_ids – This is an array of strings of one or more GUID values indicating the Permission Groups the user should be part of.

A full example is below:

{
"name": "mycorp", "provider_type": 
"oidc", "redirect_uri": "https://connect.buildingengines.com/sso_login/mycorp/sso_callback_oidc", 
"issuer": "https://mycorp.example.com/adfs",
"response_type": "code",
"client_id": "PC-98765-XXX-12345-PRD",
"audience": "PC:URI:BLDENG-MYCORP-EXAMPLE-PRD",
"email_claim": "upn",
"openid_configuration_url": "https://mycorp.example.com/adfs/.well-known/openid-configuration", 
"additional_request_arguments": {
"authorization": "true" 
}
"authorization_settings": { 
"role_claim": "role", 
"roles": [{
"pattern": "^MANAGER.*-DEV$",
"job_function_id": "99d614d9-4579-4065-b9a0-91350535ef37", 
"permission_group_ids": [
"8b46a82f-e90d-429b-8f16-2fa72e6de48c",
"fb673a72-4b63-4a0f-8cd6-c98a85483168” ]
},
{
"pattern": "^VIEWER.*$",
"job_function_id": "5977d723-5987-47b3-a67e-231f055e3ce6”, 
"permission_group_ids": [
"5131d723-a012-47b3-a67e-231f055e3ce6" ]
}]
} 
}

   GET /auth/sso_authentication_service/{{name}}

This will return an Authorization Service configuration based on the name of the configuration as above.

   PATCH/PUT /auth/sso_authentication_service/{{name}}

This will allow updating the values of the SSO configuration based on the name.