FirstSpirit Cloud: user management and access management

Here, you will find information about the user access right management for FirstSpirit Cloud, FirstSpirit, GIT and Bamboo.

It is aimed at

• FirstSpirit project administrators
• Users with the User Manager role

The most important information:

• Concept and function scope
• Detaillied instructions
• Identity provider connection for user management in the FirstSpirit Cloud

For user management and access rights management, FirstSpirit Cloud uses the open source software Keycloak. Keycloak is a single sign-on (SSO) solution for web applications and RESTful web services.

Internally, Keycloak functions as an identity provider (IdP) for FirstSpirit applications with the FirstSpirit server being the client. This ensures that user accounts are completely isolated from applications and that applications can never view a user's credentials.

Login

When a user logs in to the FirstSpirit Cloud, their login request is routed to the Keycloak server where it is authenticated. After a successful login, the Keycloak server sends an identity token to the FirstSpirit server, containing all the required information (UserID, group, validity period). This gives a user access to the required areas.

All information about the user's authorizations is contained in the identity token. The user can therefore use any other application for which he has access rights without manually logging in again. This procedure is called single sign-on (SSO).

To work with FirstSpirit Cloud, a user must

• be registered in the customer's access area,
• belong to at least one user group that allows access to at least one of the FirstSpirit Cloud environments (DEV/QA/PROD) and
• be associated with an access rights group (e.g. editor).

These criteria are fulfilled in a data area called realm with an appropriate configuration. The access rights are configured within FirstSpirit.

Realm

Realms are central organizational tools for access rights management. A realm is a configuration unit in which data records of

• users
• groups
• mappings between users and groups

are defined and managed.

Realms are isolated from each other. This means that a realm cannot access any information in another realm. Any FirstSpirit Cloud customer has exactly one associated realm, and this realm can be accessed only by that customer.

Users

A user is an identity that can log into your system. In FirstSpirit Cloud, the following information must be available for each user:

• first name
• last name
• e-mail address (also used as the FirstSpirit user name)
• membership in one or more groups

Users receive permissions exclusively by inheriting them from one or more groups or roles. For this, the user must be a member of such a group or be associated with a role.

Groups

Groups are used to manage multiple users at the same time. A user receives permissions by being associated with one or more groups.

Group names are usually composed of the customer name as a prefix, and a access rights-specific suffix, separated by a hyphen.

Example: testcustomer-git-user
testcustomer: customer name
git-user: user with Git access rights.

Keycloak and FirstSpirit use case-sensitive naming. This is especially important for Keycloak and FirstSpirit group mapping.

Groups in the default environment

The FirstSpirit Cloud contains three default environments: Dev (Development), QA (Quality Assurance) and Prod (Productive). See also the FirstSpirit Guide.

All three environments contain almost the same projects. Differences in the projects are determined by the customer.

Changes to the template and the settings are regularly moved to the next environment to avoid different development statuses.

While Dev and QA usually contain test data, the Prod environment contains the entire live project's content.

<customer_name>-users-dev: development environment
The development environment allows one or more developers or editors to work without interfering with each other's work, or with the code used in the live environment. A group with the "users-dev" suffix exists for this environment by default.
Example:
"testcustomer-users-dev": users must belong to the "testcustomer-users-dev" group to work in the development environment.

<customer_name>-users-qa: quality assurance environment
In the QA environment – also called staging or test environment – you can test the developed segments to check their quality before the work is transferred to the productive environment. Therefore, this is an almost exact replica of the productive environment. A group with the "users-qa" suffix exists for this environment by default.
Example:
"testcustomer-users-qa": users must belong to the "testcustomer-users-qa" group to work in the quality assurance environment.

<customer_name>-users-prod: productive environment
The productive environment contains all published projects that are already filled with content and available to your customers. A group with the "users-prod" suffix exists for this environment by default.
Example:
"testcustomer-users-prod": users must belong to the "testcustomer-users-prod" group to work in the productive environment.

Further groups

The functions and permissions of further default groups are pre-configured and can be adapted project-specifically if required.

<customer_name>-chiefeditors
Editors with extended permissions: direct content release, editing permissions and user permission assignment, maintenance of certain menu items.

<customer_name>-developer
FirstSpirit template developers: configuring templates, Git access (changes in source code).

<customer_name>-editors
Classic editors: viewing all content, editing specific content. No release permissions.

<customer_name>-git-user
Git access.

<customer_name>-projectadmins-dev
Project administrators for the development environment: setting FirstSpirit group permissions, setting languages and background process flows to update websites.

<customer_name>-projectadmins-qa
Project administrators for the QA environment.

<customer_name>-projectadmins-prod
Project administrators for the productive environment: managing publicly available websites.

<customer_name>-template-distribution
Permissions to transfer project templates from the development environment to the QA environment and on to the productive environment.

Assigning permissions

Access permissions can only be set on the FirstSpirit server by configuring external groups.

The following permissions can be assigned to a group:

• Access to FirstSpirit (e.g. editor, chief editor, project administrator, etc.).
• Access to the Git repository (Git user)
• Access to Bamboo
• Access to the artifactory

In FirstSpirit Cloud, you cannot assign rights through roles, the only Exception being the User Manager role.

User Manager role

Roles represent a user type or category. The roles of an administrator, user, manager, or employee are all typical for an organization. For access and permissions, applications can also use roles instead of groups. The assignment of permissions is intended for the FirstSpirit Cloud in the first place and is therefore using groups.

In FirstSpirit, a user with the User Manager is responsible for user management. In a realm, at least one user must have this role assigned to create further users and assign permissions. Crownpeak's default settings assign this role from the start to the first user in your FirstSpirit Cloud.

This role cannot be assigned to a group. Also, it is not possible to create a group with the permission to manage users.

Federations

As with customers, each partner company also receives exactly one realm when it supports FirstSpirit Cloud customers in implementing projects.

To access the customer environment, a partner company's realm is connected to the customer's realm. This mechanism is called federation and is set up by Crownpeak at the customer's request. Once set up, the partner company's users are available in the customer's realm without any associated access rights. User permissions within the customer's realm are defined by the customer.

Mapping

On the Keycloak server, users are given access permissions by being assigned to groups. Access permissions and workspaces are linked with FirstSpirit server groups.

To link groups between Keycloak and FirstSpirit, identical group names must be used on the FirstSpirit server and on the Keycloak server.

• The groups are created in Keycloak or were created by default.
• External groups are created in FirstSpirit. The group name in the "External name" field must be identical to the group name in Keycloak.

Example: Group name mapping:

• testcustomer-editor
• testcustomer-git-user
• testcustomer-users-dev
• testcustomer-users-qa
• testcustomer-users-prod

For details, see Managing users.

An Identity Provider (IdP) stores and verifies user identities. For services such as FirstSpirit Cloud, the IdP serves as a central access system where users can log in. Typically, IdPs are cloud-hosted and work with single sign-on (SSO) providers to authenticate users.

Internally, Keycloak is an IdP for the FirstSpirit Cloud. However, you can also use your own IdP for user management.

Your IdP connection to FirstSpirit Cloud offers a number of advantages:

• Stronger authentication: An IdP provides solutions that ensure secure access across applications.
• Simplified user management: Another solution offered by most IdPs is single sign-on (SSO), which saves users from creating and maintaining multiple usernames and passwords.
• Better visibility: An IdP aggregates all user activity, providing visibility into all users and their permissions.
• Easier identity management: A central identity management facilitates onboarding and offboarding new editors and thereby also increases security.
• With your own IdP, you can implement multi-factor authentication. This is currently not supported by Crownpeak.

With the exception of multi-factor authentication, these benefits already apply to Keycloak as an internal IdP in FirstSpirit. By extending your IdP to FirstSpirit, you get an additional synergy effect.

Scope of functions

New users and automatic updating

If you use an IdP, the FirstSpirit Cloud dialog offers logging in with the provider's login as an option. If the user selects this option, then he enters his login data, which he needs at the IdP (e.g. Azure).

If you use multi-factor authentication, this step also takes place at the external IdP.

If the login is successful, the user data – user ID, email address, first name, last name, etc. – is transferred from the IdP to Keycloak, and the respective user is updated. New users are created automatically in Keycloak.

Manually adding users to groups

The IdP has no information about the user's access permissions to FirstSpirit Cloud applications. Therefore, including the user into groups cannot be automated. A user manager must add a new user to the required groups.

Access to all applications with SSO login

If the user is logged in to the IdP, he has access to all of the applications within his company and FirstSpirit Cloud if access permissions were set up in Keycloak.

The login works regardless of the application, in which it was performed. FirstSpirit Cloud applications (e.g. Git, Bamboo, etc.) do not require an additional login if the user already logged in within one of the company's applications.

OIDC / SAML protocols

FirstSpirit Cloud supports IdP login with the OIDC and SAML protocols.

• OIDC
  OpenID Connect (OIDC) is an open authentication protocol that uses OAuth 2.0 and adds an additional identity layer. OIDC allows clients to confirm the identity of an end user using authentication by an authorization server.
• SAML
  Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization identities between security domains. The XML-based protocol allows the transfer of authentication and authorization information from an IdP to the FirstSpirit Cloud. SAML provides functions to describe and transfer security-related information correctly and safely.

Setting up the first user

The first user account of your FirstSpirit Cloud is created by Crownpeak and associated with the User Manager role. As a User Manager, the first user has the rights to create other users and manage all other settings in Keycloak and in FirstSpirit.

Requesting the first user

Place a support request

as an e-mail to help@e-spirit.com and provide the first user's information: first name, last name, business e-mail address

or as a ticket:

• In the Support portal, select Submit Support Request
• Enter your e-mail address and select the FirstSpirit product line
• Optionally: enter the priority, product version and FirstSpirit component
• Case reason: Service Request
• Subject: New Account
• Enter the first user's information in the description: first name, last name, business e-mail address

Activating the first user

Once the user is created, Crownpeak will confirm your request via e-mail.

You will first need to activate the first user's account:

• Open https://accounts.e-spirit.cloud/
  
• Enter the first user's e-mail address that was communicated to Crownpeak
• Solve the captcha
• Click Request new password

You will receive a verification e-mail:

• Click on the link in the e-mail
• Create a password

The first user is now set up. The fist user receives the User Manager role and can add and manage further users.

User Manager: Keycloak login

• Enter your realm's address in your browser:
  https://sso.e-spirit.hosting/auth/admin/<customer_name>/console/
  Replace <customer_name> with your FirstSpirit Cloud customer name
  
• If no identity provider has been integrated yet, enter the user name (e.g. your e-mail address) and the password in the login fields and click Sign In.
• If an identity provider is already in use, click <customer_name> IDP (see: First login for new users after IdP integration)

The user management form with your FirstSpirit user name will open. Here you can manage users and groups.

Managing users

User Manager: creating a new user

• Open the Users area.

• Click Add User in the upper area.
  

• Fill in the fields:
  
  • Username (mandatory field)
    Use only the user's business email address as the username.
  • Email
    Use only the user's business email address.
  • Email verified
    Change the entered e-mail's verification status to Yes.
  • First Name
    User's first name
  • Last Name
    User's last name
  • Groups
    When creating a user, you can already select groups which that user shall be in and whose rights shall be inherited. You can also select such groups later.
• Click Create to save the user entry.

The following email template serves as a suggestion / assistance for your email and can be customized according to your wishes.

User: activating own user account

After the user's account has been created, they need to activate it on their own. Notify the user about the necessary steps:

• In https://accounts.e-spirit.cloud/ the user needs to enter their e-mail address which the User Manager has used to create the user entry.
  
• The user will receive a verification e-mail:
  • The user needs to click the link in the e-mail.
  • The user needs to create a password.
• → Your user account is now set up. The user can log in in FirstSpirit.

User Manager: editing user entries

Once a user is created, you can edit other properties of the user.

• Open the Users area.
• Click the username in the Username column. The entry's detailed view will open.
  

User Manager: deleting users

To delete the user entry:

• Open the Users area.
  
• Select one or more users in the list and click Delete user in the upper area.
• Alternatively: Click the three-dot-menu in a user entry's row and select Delete.
• Open the user entry's detailed view. Click Action in the upper are and select Delete.
  
• Confirm with Delete.

Managing user groups

Creating a user group

Typically, the user groups you need to get started with FirstSpirit Cloud are already in place and do not need to be created.

• Open the Groups area.
  
• Click Create group.
• Enter the group's name in the pop-up.
  Recommendations for naming groups
• Confirm with Create.

Associating users to user groups

• Open the Users area.
• Click on the user entry in the Username column to open the user entry's detailed view.
• Open the Groups tab.
  In the list, the user's memberships are displayed.
  
• Click Join group.
  A pop-up with the list of all available groups is displayed.
• Select one or more groups and click Join.

Removing users from user groups

• Inside a user entry row in the list, click Leave.
• Alternatively: Select one or more entries in the list and click Leave in the upper area.
• Confirm with Leave.

Deleting user groups

It is not possible for a User Manager or any other user role within your company to Delete user groups.

To delete a user group, create a Support Request.

Managing a user's roles

• Open the Users area.
• In the user entry's detailed view, open the Role Mappings tab. Your realm's roles are displayed.
  

Assigning the User Manager role

As a User Manager, you can assign another user with the User Manager role.

• In the upper area, click Assign role.
• In the pop-up, select the User Manager role and click Assign.
  The role is assigned instantly.

Unassigning the User Manager role

As a User Manager, you can remove the User Manager role from other users.

• Select the User Manager entry in the list and click Unassign in the upper area.
• Alternatively: Click the three-dot-menu in the User Manager role's row and select Unassign.
• Confirm with Remove.

Creating external groups on FirstSpirit server

The Keycloak server and the FirstSpirit server are connected by groups with exactly matching group names.

Activities on the Keycloak server are not automatically transferred to the FirstSpirit server. You must create an associated external group on the FirstSpirit server for each group on the Keycloak server.

• Log in on your FirstSpirit server, open the Server Manager, select the required project and switch to the properties.
• Select Groups to display the group overview.
  
  External groups are highlighted as External group in the Users column. No users are associated with such groups in FirstSpirit because the groups are managed in Keycloak.
• Check, which Keycloak groups already do exist.

Creating a new group with an identical group name

• Right-click on the group list and select Create New Group.
  
• Mark the entry as External group.
• Enter the keycloak group's exact name in the External name field.
• Confirm with OK.

Configuring access permissions

• You can now configure the permissions for the new group.

Creating a federation

Each FirstSpirit partner company has exactly one realm. If you wish your partner to work on your projects, your realm needs to be connected to that of your partner's.

Place your support request with help@e-spirit.com and provide the user information:

• Partner company's name
• Name or ID of one or more users in your company that shall have the User Manager role

Or create a ticket.

The Identity Provider (IdP) concept is explained above.

FirstSpirit Cloud is able to connect to your IdP.

For activation, we prepare your FirstSpirit Cloud access while you customize your IdP.

See the required setup steps below.

Creating Support request

Inform us

• about your intention to connect your FirstSpirit Cloud to your IdP;
• about the connection protocol to be used.

Write to us at help@e-spirit.com or create a ticket.

We will prepare your FirstSpirit Cloud for the IdP integration and send you links that you need for the preparation in your IdP:

OIDC

• You will receive a Redirect URI
  E.g.: https://sso.e-spirit.hosting/auth/realms/your-realm
• Setting up the IdP with OIDC.

SAML

• You will receive an Application ID URI
  E.g.: https://sso.e-spirit.hosting/auth/realms/your-realm
• You will receive a redirect URI
  E.g.: https://sso.e-spirit.hosting/auth/realms/<REALM NAME>/broker/<IDP ALIAS>/endpoint
• Setting up the IdP with SAML.

Requirements

• You need to make sure that e-mail functionality works in your Keycloak realm.
• All users (including test users) must have an e-mail address and be able to access their e-mails.

Communication of IdP set-up completion and your data to Crownpeak

OIDC

• Set up your IdP using the received redirect URI.
• Inform Crownpeak that the IdP set-up is complete and provide the following information:
  • Configuration URL / Metadata
  • ClientID
  • ClientSecret
  • E-mail address to set up the User Manager role

SAML

• Set up your IdP using the received Application ID URI and Redirect URI.
• Set up ID, access token, and SAML token. Use your e-mail address for setting this up.
• Inform Crownpeak that the IdP set-up is complete and provide the following information:
  • E-mail addresses used for ID, Access token, and SAML token
  • Federation Metadata Document URL
  • E-mail address used to set up the User Manager role

IdP definition in the FirstSpirit Cloud

The IdP in the FirstSpirit Cloud is defined by Crownpeak.

You will be notified by Crownpeak that the configuration is complete. You can then proceed with tests in FirstSpirit Cloud.

Workshop

After the configuration is complete, you will be invited to a workshop. User access will be tested and problem solutions will be discussed if needed.

New customers: Organization of groups and users in the FirstSpirit Cloud

All user data is managed in the IdP and automatically updated in the FirstSpirit Cloud. Manual user management in the FirstSpirit Cloud (Keycloak) is therefore not necessary.

• Overview of FirstSpirit Cloud groups: Groups in the default environment
• Adding users to groups: Managing a user's roles
• Creating external groups on FirstSpirit server

You can use the following instructions as a template to create work instructions for users in your organization.

A distinction is made between new users in the FirstSpirit Cloud with an external IdP and existing users who have previously logged into the FirstSpirit Cloud without an external IdP.

First login for new users after IdP integration

Precondition: a simple access to the FirstSpirit Cloud applications has been requested.

• Open the access URL to your productive system.
  Example: https://<customer_name>.e-spirit.hosting
• Select the IdP login:
  
  → You will be forwarded to your company's IdP.
• Log in using the IdP.
  → You are now logged in and will be redirected to the application including all access information.

First login for transferred users after IdP integration

When an IdP is integrated, users that have been created prior to such an integration need to connect their account with the IdP.

For transferring an existing user to manage them with IdP, their username needs to remain unchanged.

• Log in using your IdP.
  → You will be requested to connect your existing account with the IdP.
• Click Add to existing account.
  
  → You will receive an e-mail to your e-mail address that needs to be verified.
• Open the link in the e-mail.
  → Your account is now connected with the IdP.

User account confirmation

After the first login, an e-mail with a confirmation link will be sent to the e-mail address you provided.

• Click on the link in the e-mail.
  → Your Keycloak user account is now connected to the IdP.