Identity and Access Management User Guide

Intellectual Property

Protected by patents in the U.S. and Europe:

US10430037, EP2684143, US8365188, EP1997041, US8880710, EP1979840, US8898309, EP1979839

Tailoring your Celebrus security to meet your orgnisation’s requirements.

1. Introduction

Celebrus offers several options for Identity and access manager (IAM) allowing you to tailor Celebrus to your organisations needs.

Celebrus has two distinct access realms targeting different functions:

Configuration
Provides access to Celebrus configuration through the Configuration Manager web app and Operations API. Access permissions are grouped by activity, for example permissions relating to Data Collection include Collection Rules, Currency Exchange Rates and Universal Data Sources, whereas Data Activation includes Data Loader, Data Streams and File Transfer.
Operations
Provides access to monitoring and DEVOPS functions, surfaced through the Operations Dashboard. Access permissions present for administration, monitoring and snapshots.

As part of your Celebrus deployment, you decide on an identity provider (IDP).

An identity provider (IDP) provides at least an authentication capability.

In most cases your IDP also provides a set of claims for an authenticated user. These claims represent the roles or groups to which the user belongs. Celebrus maps these to permissions which restricts the activities of a user. With this approach all user management is performed by the IDP.

Where an IDP provides only authentication, the mapping between users and roles must be maintained by Celebrus. The is a big disadvantage as it requires user management in both your IDP and Celebrus. Only the configuration realm allows this hybrid solution.

For a practical walk-through of setting up Celebrus to operate with different IDPs, see the Identity and Access Management Playbook.

2. Identity and access management (IAM)

Celebrus supports several options for identity and access management.

Celebrus Cloud supports only OIDC.

PROTOCOL	REALMS	SSO	NOTES
In-built	configuration operations		User name and password authentication. User and assigned roles are stored within a database. Only seeded hashes of passwords are stored in the database.
OIDC	configuration¹ operations	yes	OpenID Connect (OIDC) is the modern day standard for authentication and authorisation.
LDAP	configuration¹ operations		Available in nearly all organisations.

PROTOCOL

REALMS

SSO

NOTES

In-built

configuration operations

User name and password authentication. User and assigned roles are stored within a database. Only seeded hashes of passwords are stored in the database.

OIDC

configuration¹ operations

yes

OpenID Connect (OIDC) is the modern day standard for authentication and authorisation.

LDAP

configuration¹ operations

Available in nearly all organisations.

Legacy support for SAML2 and Kerberos is partially available but will be deprecated in a future release. Neither of these are suitable for new installations. Neither are supported within Celebrus Cloud.

LEGACY PROTOCOL	REALMS	SSO	NOTES
SAML2	configuration¹	yes	SAML2 is available only for the configuration realm. As such its use it not recommended for new installations and will be deprecated in a future release.
Kerberos	operations	yes	Kerberos is available only for the operations realm. As such its use is not recommended for new installations and will be deprecated in a future release.

LEGACY PROTOCOL

REALMS

SSO

NOTES

SAML2

configuration¹

yes

SAML2 is available only for the configuration realm. As such its use it not recommended for new installations and will be deprecated in a future release.

Kerberos

operations

yes

Kerberos is available only for the operations realm. As such its use is not recommended for new installations and will be deprecated in a future release.

¹ Configuration realm support provides full IAM or a hybrid approach where your IDP performs authentication and the Celebrus inbuilt IDP provides the mapping of users to roles. This hybrid approach may be useful in some circumstances, but results in a user management requirement on both your IDP and the Celebrus inbuilt one. As such its use is not recommended.

Inbuilt, out of the box identity providers are available for both configuration and operations realms. These require using user name and password credentials. Users and role assignments roles are stored within a database.

For the configuration realm, users and roles are stored within the configuration repository, as managed by the Configuration Server.

For the operations realm, user and roles are stored within the operations database, as managed by the Operations Server.

In both cases user passwords are not stored, only seeded hashes of the passwords are. Someone with read access to the database cannot determine the original passwords.

This inbuilt approach is a really good option when you’re starting out with Celebrus, but they do have their shortcomings:

no support multi-factor authentication
no control over the password policy, such as password complexity and lifetime
it’s yet another password

Using your IDP such as OIDC, or LDAP is more effort for the initial setup, but provides significant advantages, including:

allows for multi-factor authentication
integrated with your organisations user management, so you don’t have to add/remove users within Celebrus
full control over password policies
in some cases, support for single sign-on (SSO)

3. Identity providers

If your needs aren’t met by the options described previously, another option is to use a broker. In this setup your IDP acts as an intermediary between Celebrus and your protocol of choice.

Popular commercial and opensource offerings such as Okta and Keycloak cater for this use case, in addition to provide full IAM in their own right.

Such offerings also cater for different authentication flows depending upon the target realm and the origin of an authentication request. For example it’s possible to have a single, common authentication flow for both Configuration and Operations realms, or to have an authentication flow for each. Similarly flows can be defined depending upon the origin of an authentication request for cases where you wish to differentiate between your employees and those of a third party providing a service to your organisation.

4. User roles

The default system administrator role SYSADMIN has privileges to access and modify any configuration within the Celebrus system.

Every program and every privileged user of the system should operate using the least amount of privilege necessary to complete the job.

— Jerome Saltzer
Communications of the ACM

Consider how individuals within your organisation access and use the Celebrus system. Does a user who is configuring data collection aspects of the system (data sources) also need to configure personalisation? If not, create separate roles to represent these different tasks. This allows restrictions to be placed on users so they can only access the information and resources that are necessary for their legitimate day to day activities; the principle of least privilege.

The table below shows the default roles which are created when Celebrus is installed:

ROLE	RESPONSIBILITY	CONFIGURATION MANAGER APPS
SYSADMIN	Super user	All (including the ability to administer users in the Users and Roles app).
Data Analyst	Understand the data and help the organisation make better business decisions.	Machine Learning Explorer, Data Loader, Data Streams, File Transfer
Data Engineer	Everything which is needed to collect, transform, and deliver data to the organisation.	Collection Rules, Currency Exchange Rates, Data Enrichment, Data Mapping, Event Sample, Geolocation, Semantic, Universal Data Sources
DevOps Engineer	Deployment of the Celebrus system, introduction of new nodes in to the system, port allocation etc.	Deployment, Email, Event Store, Keystore, Licensing
Marketing Analyst	Manage the personalisation and user experience for customers on digital channels.	Offline Segmentation, Personalisation, Templates
Security Engineer	Manage the security, data protection and identity on your digital channels.	Audit Trail, Data Protection, Digital Fraud, Users and Roles

ROLE

RESPONSIBILITY

CONFIGURATION MANAGER APPS

SYSADMIN

Super user

All (including the ability to administer users in the Users and Roles app).

Data Analyst

Understand the data and help the organisation make better business decisions.

Machine Learning Explorer, Data Loader, Data Streams, File Transfer

Data Engineer

Everything which is needed to collect, transform, and deliver data to the organisation.

Collection Rules, Currency Exchange Rates, Data Enrichment, Data Mapping, Event Sample, Geolocation, Semantic, Universal Data Sources

DevOps Engineer

Deployment of the Celebrus system, introduction of new nodes in to the system, port allocation etc.

Deployment, Email, Event Store, Keystore, Licensing

Marketing Analyst

Manage the personalisation and user experience for customers on digital channels.

Offline Segmentation, Personalisation, Templates

Security Engineer

Manage the security, data protection and identity on your digital channels.

Audit Trail, Data Protection, Digital Fraud, Users and Roles

4.1. Mapping roles from your IDP to Celebrus role names

When the inbuilt Celebrus IDP isn’t being used, one consideration is the mapping of roles from your IDP to Celebrus roles.

The Operations Server has fixed roles. You can map your roles to these using the appropriate configuration within the application-production.properties file. For OIDC the mapping using the settings as shown below, where each entry has one or more role names from your IDP. Where multiple roles are specified they are separated by a comma.

# OIDC role mapping - enter comma separated list of roles to be mapped.
# celebrus.security.oauth2.client.provider.[provider-name].admin-role-mapping=myAdmin,myOtherAdminRole
# celebrus.security.oauth2.client.provider.[provider-name].user-role-mapping=myView
# celebrus.security.oauth2.client.provider.[provider-name].snapshot-role-mapping=mySnapshot
# celebrus.security.oauth2.client.provider.[provider-name].logview-role-mapping=myLogview

The Configuration Server has customisable roles. Predefined roles are defined upon install which can can be modified, deleted and added to meet your business requirements. This allows you to name your roles to match you IDP based roles. Alternatively roles can be mapped using the celebrus.security.role.mappings property specified within the secure.properties file. In the example below the Azure AD role which is a UUID is mapped to a Celebrus role.:

celebrus.security.role.mappings={ "mappings": [ { "from" : "b3a3ea65-4a8e-4778-81bc-fa06516416ba", "to":"SYSADMIN" } ] }

5. Inbuilt IDP setup

Using the inbuilt IDP of Celebrus is the default after the install. The setup is detailed here for completeness.

5.1. Configuration Manager

Set the JSON field /security/module to:

"com.speed_trap.webswing.server.CelebrusSecurityModule"

Set the JSON field /security/config to:

{
    "users" : [ ],
    "extensions" : [ ],
    "logoutUrl" : "/"
}

Set the JSON field /celebrus/security to:

{
	"module" : "INHERITED",
	"securityContextPerTab" : false
}

5.2. Configuration Server

Edit <Celebrus install>\ConfigurationServer\config.properties, setting:
```
useLdapAuthentication=false
useLdapRoleAssignments=false
```
Restart the Configuration Server.

5.3. Operations Server

Edit the <Dashboard install>/application-production.properties*, setting:

celebrus.security.auth-method.ldap=false
celebrus.security.auth-method.file=true
celebrus.security.auth-method.sso=false
celebrus.security.auth-method.oidc=false

5.4. Lost credentials recovery

In the event that a Celebrus deployment has only a single user, and the credentials for that user have been forgotten, then a few options exist to recover:

Import configuration from another, working system.
Reinstall.
Fix the SMTP and user configuration manually and re-import. The Configuration Server exports its current configuration to the <install directory>/ConfigurationServer/exports area.

It’s possible to take this configuration and re-import it in to the server by placing the modified copy within <install directory>/ConfigurationServer/imports. The SMTP configuration is located in the resources/emailConfiguration/emailConfiguration.xml file. User configuration is stored within resources/users/<login name>.xml, and can be edited and re-imported in a similar fashion.

6. OIDC setup

Celebrus supported IDPs providing OIDC authorisation using JWT tokens. Opaque tokens are not supported.

You’ll need the following details from your IDP:

Client ID: ID for the Celebrus application within the OIDC provider.
Client secret: Shared secret between the OIDC provider and Celebrus.
User name attribute: The OIDC claims attribute from which the user’s name can be extracted. Typically this is preferred_username.
Provider name: A name for the provider, such as Okta or Keycloak. The name is used in several parts of the configuration to relate configuration to a single provider.
Discovery URL: The OIDC provider’s discovery URL that returns a JSON payload containing the OIDC settings. For example, the popular Okta platform’s discovery URL for a test account is typically of the form https://dev-XXXXXXXX.okta.com/oauth2/default/.well-known/openid-configuration.
Base URL: The discovery URL minus the /.well-known/openid-configuration suffix. For example, the popular Okta platform’s base URL for a test account is typically of the form https://dev-XXXXXXXX.okta.com/oauth2/default.
End session endpoint: Endpoint provided by the IDP to logout of a session. This value can be obtained from the response to the GET of the discovery URL, and searching for the key end_session_endpoint.

When using OIDC the Celebrus Configuration and Operations Servers both require out-bound connectivity to your OIDC provider. Be sure your firewall rules permit this.

6.1. Configuration Server

Edit <Celebrus Install>\secure.properties file:

Set the following:

celebrus.oidc.username.attributeName=<OIDC username attribute name>
celebrus.oidc.roles.attributeName=<OIDC role attribute name>
celebrus.oidc.issuer.uri=<OIDC base URL>
celebrus.security.role.mappings=<OIDC ROLE MAPPINGS>

For Okta, celebrus.oidc.username.attributeName is often sub, and celebrus.oidc.roles.attributeName is resource_access.

If your IDP is using a self-signed certificates, a keystore containing its certificate is required to be set as:
```
idp.trustStorePassword=<password>
idp.trustStore=<location>
idp.trustStoreType=<keystore type>
```
TIP

For an IDP with a public internet presence, the expectation would be for it to be using certificates from well known authorities so no trust store configuration is required.
Edit <Celebrus Install>\Configuration Server\config.properties file, setting:
```
useSsoAuthentication=OIDC
useExternalRoleAssignments=true
```
Ensure that the <Celebrus Install>\Configuration Server\ConfigurationServer.conf file does not contain a -DproxyHost="" line in the var-args section. The OAuth libraries will read this and overwite the issuer.uri.
Restart the Configuration Server.

6.2. Configuration Manager

Edit <Dashboard Install>\ConfigurationManager\webswing.config:

Set the JSON field /security/module to:

"com.speed_trap.webswing.security.oidc.CelebrusOidcSecurityModule"

Set the JSON field /security/config to:

{
  "importDiscoveryJson" : "<OIDC dicovery URL>",
  "callbackUrl" : "<URL of Dashboard>/config/celebrus/login",
  "clientId" : "<OIDC client ID>",
  "clientSecret" : <OIDC client secret>,
  "scopes" : "openid profile",
  "attributeMapping" : [ "id_token"],
  "logoutUrl" : "<OIDC end session endpoint>?id_token_hint=${user.id_token}&post_logout_redirect_uri=<URL of Dashboard>"
}

Set the JSON field /celebrus/security to:

{
	"module" : "INHERITED",
	"securityContextPerTab" : false
}

6.3. Operations Server

Edit the <Operations install>\application-production.properties, setting the values below:

celebrus.security.auth-method.db=false
celebrus.security.auth-method.ldap=false
celebrus.security.auth-method.oidc=true
celebrus.security.auth-method.sso=false

spring.security.oauth2.client.registration.<OIDC provider name>=<OIDC provider name>
spring.security.oauth2.client.registration.<OIDC provider name>.provider=<OIDC provider name>
spring.security.oauth2.client.registration.<OIDC provider name>.client-id=<OIDC client ID>
spring.security.oauth2.client.registration.<OIDC provider name>.client-secret=<OIDC client secret>
spring.security.oauth2.client.registration.<OIDC provider name>.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.<OIDC provider name>.scope=openid
spring.security.oauth2.client.registration.<OIDC provider name>.redirect-uri={baseUrl}/login/oauth2/code/{registrationId}
spring.security.oauth2.client.provider.<OIDC provider name>.userNameAttribute=<OIDC username attribute>
celebrus.security.oauth2.client.provider.<OIDC provider name>.logout-uri={baseUrl}/oauth2/default/v1/logout
celebrus.security.oauth2.client.provider.<OIDC provider name>.post-logout-redirect-uri=<Celebrus dashboard URL>
spring.security.oauth2.client.provider.<OIDC provider name>.issuer-uri=<OIDC base URL>
spring.security.oauth2.resourceserver.jwt.issuer-uri=<OIDC base URL>

# The admin-role implicitly gives access to everything.
# The default role names are defined below.
# Change these to map to your IDP role/group names.
# Comma-separated list of roles/groups are allowed.
# For example, if the users within your organisation who were to be Celebrus administrators
# all belonged to an existing OIDC group called WebApps, then you would set:
#
#    celebrus.security.oauth2.client.provider.okta.admin-role-mapping=WebApps
#
celebrus.security.oauth2.client.provider.<OIDC provider name>.admin-role-mapping=admin
celebrus.security.oauth2.client.provider.<OIDC provider name>.user-role-mapping=view
celebrus.security.oauth2.client.provider.<OIDC provider name>.snapshot-role-mapping=snapshot
celebrus.security.oauth2.client.provider.<OIDC provider name>.logview-role-mapping=logview

Restart the Operations Server.

7. SAML2 setup

Support for SAML2 is limited to the Configuration Server. It is recommended to use OIDC if possible.

7.1. Configuration Server

Edit <Celebrus Install>\Configuration Server\config.properties file, setting:
```
useSsoAuthentication=SAML
useExternalRoleAssignments=true
```
Restart the Configuration Server.

7.2. Configuration Manager

Edit <Dashboard Install>\ConfigurationManager\webswing.config:

Set /security/module to:

"com.speed_trap.webswing.security.saml2.CelebrusSaml2SecurityModule",

Edit/securityclasspath"], setting its value to:

[ "${webswing.rootDir}/security/saml2/*", "${webswing.rootDir}/ConfigurationManager.jar" ],

Set /security/config to:

{
  "extensions" : [ "com.speed_trap.webswing.security.saml2.CelebrusSaml2SecurityExtension" ],
  "identityProviderMetadataFile" : "https://<adfs-server-domain>:<port>/FederationMetadata/2007-06/FederationMetadata.xml",
  "serviceProviderConsumerUrl" : "https://<dashboard-server-domain>:<port>/config/celebrus/login",
  "serviceProviderEntityId" : "https://celebrus.com/config/entity",
  "authnRequestSigned" : false,
  "nameIdPolicyFormat" : "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "rolesAttributeName" : "roles",
  "keyStore" : "${webswing.rootDir}/application.keystore",
  "decryptionKeyAlias" : "samlrequests",
  "keyStorePwd" : "<keystore-password>",
  "keyPwd" : "<key-password>",
  "singleLogout" : true,
  "com.speed_trap.webswing.security.saml2.CelebrusSaml2SecurityExtension" : {
    "configurationServerAssertionConsumerUrl" : "https://<configuration-server-domain>:<port>/saml/acs"
  }
},

Set /celebrus/security to:

{
	"module" : "INHERITED",
	"securityContextPerTab" : false
}

Restart the Operations Server.

8. LDAP setup

8.1. Configuration Manager

Set /security/module to:

"com.speed_trap.webswing.server.CelebrusSecurityModule"

Set /security/config to:
```
{
}
```

Set /celebrus/security to:

{
	"module" : "INHERITED",
	"securityContextPerTab" : false
}

8.2. Configuration Server

Copy <Celebrus install>\LDAP\ldap.cfg to <Celebrus install>\ConfigurationServer.
Edit <Celebrus install>\ConfigurationServer\ldap.cfg:
The file details what the configuration items are such as the address of the server and the search template used to LDAP attributes to be used to check group membership for the named user.

Further details and examples are provided in the file itself.
Edit <Celebrus install>\ConfigurationServer\config.properties, setting:
```
useLdapAuthentication=true
useLdapRoleAssignments=true
```
If you wish to use hybrid authentication (not recommended for new installations), further edit <Celebrus install>\ConfigurationServer\config.properties, setting:
```
useLdapRoleAssignments=false
```
The specific permissions associated with a role are defined within the Celebrus. For example, you may have a business analyst called John Smith who is a member of the LDAP group BusinessAnalysts, withinn Celebrus, you define a matching role called BusinessAnalysts who are allowed to log into the Configuration Manager and work with the Machine Learning Explorer.

If you are using LDAP for role assignment, the role names within Celebrus must match the LDAP groups you intend to use.

To assist in the setup of LDAP, specific LDAP logging is available. This can be enabled through the Operations Dashboard DevOps pages.
Restart the Configuration Server.

The Identity and Access Management Playbook contains a walk through of how to configure LDAP using Apache Directory as an example.