1. Concept

The FirstSpirit Cloud uses Keycloak to manage users.

Keycloak is an open source solution from the Red Hat company for managing digital identities and permissions.

1.1. Realms

The administration takes place in so-called Realms. These are configuration units, in which

  • users

  • groups

  • assignment of users to groups

  • permissions

are defined.

Each FirstSpirit Cloud customer has their own realm that only they can access and see.

Partner companies that support e-Spirit customers in the implementation of projects have their own realm. This is assigned to the realm of the respective customer (or customers) to enable access to the customer’s resources. The customer defines which authorizations the partner company receives in each case.

Note: To create users for partner companies, see chapter Collaboration with partner companies.

1.2. Users

The following information must be available for each user:

  • First name

  • Last name

  • E-mail address
    (Note: This must be a business email address. Gmail, Yahoo, GMX, etc. are not allowed.)

  • Group membership

1.3. Groups

Permissions are assigned to individual users via groups.
Among others, the following permissions can be assigned:

  • access to FirstSpirit (e.g. Editor, Chief-Editor, Project-Admin, etc.)

  • access to the Git repository (GIT User)

  • access to Bamboo

  • access to the Artifactory

For users to get permissions, they must be assigned to the desired groups.

2. User Management

Manage users who should have access to the FirstSpirit Cloud simply by using the Keycloak interface of the FirstSpirit Cloud itself.

Note: To create users for partner companies, see chapter Collaboration with partner companies.

2.1. Role User-Manager

For user management you need a user with the role
User-Manager

Use this to

  • create new users

  • grant permissions to users

  • remove or change permissions

  • delete users

To access this role, please contact e-Spirit TechnicalSupport, per

Please provide TechnicalSupport with the following information

  • First name

  • Last name

  • E-mail address
    (Note: This must be a business email address. Gmail, Yahoo, GMX, etc. are not allowed.)

of the user who should receive the User-Manager role.

You can use the user User-Manager, which is initially created by TechnicalSupport, to make further users User-Managers yourself.

2.2. Log in (Keycloak)

Log in to your realm on the e-Spirit Keycloak server with the user who has the User-Manager role.
In our example, the realm name is Testcustomer.

https://sso.e-spirit.hosting/auth/admin/<customer_name>/console/

You will receive the following login mask:

Keycloak Log in
Figure 1. Keycloak log in

2.3. Create users

Note: To create users for partner companies, see chapter Collaboration with partner companies.

Click on the Users area:

Users area
Figure 2. Area Users

To check if and which users already exist, use View all users.

Click Add user:

Create user
Figure 3. Create user

Enter the required data for the user in this dialog:

Field name Description

Username

Enter the user’s e-mail address here.
(Note: This must be a business email address. Gmail, Yahoo, GMX etc. are not allowed.)

Email

Enter the user’s email address here as well.

First Name

Enter the first name of the user here.

Last Name

Enter the last name of the user here.

Groups

Select the desired group to grant the user the desired permissions.
Search for available groups by entering a letter of your customer name, for example.

For more information on which groups are available, see also

Then click Save.

If no Save button is displayed, you may not have sufficient permissions. In this case, please contact e-Spirit TechnicalSupport.

Create further users in the same way.
To do this, switch back to the Users area (see Create users).

2.4. Groups

2.4.1. Check

You can see which groups are available in Keycloak in the Groups area:

Groups area
Figure 4. Groups area

Group names are usually composed of the customer name and a suffix that refers to the particular permission.

Users who are members of the group
…​-git-user
have access to the Git.

The other groups refer to permissions regarding work with FirstSpirit.
You assign the permissions to these groups in FirstSpirit.

To check which groups contain which users, double-click on the desired group name.
Switch there to the Members tab:

Members of a group
Figure 5. Members of the …​-projectadmins-dev group

2.4.2. Assign or change

To assign new groups to users or modify existing ones, switch back to the Users area:

_Users_ area
Figure 6. Users area

Show existing users with View all users:

List of users
Figure 7. List of users

or search specifically for a user using the Search box.

To edit data of a user or permissions, click on the ID of the respective user or on Edit:

Detailed view
Figure 8. Detailed view

Switch there to the tab Groups:

Membership
Figure 9. Memberships of the user 'Administrator'
Box Description

Group Membership

shows all groups in which the user is a member and has the corresponding permissions,
in the example the group …​-projectadmins-dev.

Available Groups

shows all available groups

  • To assign the user to a group, select the desired group and click Join.

  • To remove permissions from the user, select the desired group and click Leave.

2.5. Assigning the role User-Manager

You can assign the User-Manager role to users yourself.
Thus you make possible that also other colleagues apart from you can create new users and assign permissions.

To do this, switch to the Users area:

_Users_ area
Figure 10. Users area

Show existing users with View all users ein:

List of users
Figure 11. List of users

or search specifically for a user using the Search box.

Click on the ID of the user who should get the role User-Manager (or Edit).

Switch to the Role Mappings tab:

Role Mappings
Figure 12. Role Mappings tab
Box Description

Available Roles

shows all available roles

Assigned Roles

shows all roles the user holds

Effective Roles

shows all available roles, including inherited roles

  • To assign the User-Manager role to the user, select the User-Manager role in the Available Roles box and click Add selected>.
    The user can then in turn create new users and assign groups or permissions.

  • To remove the User-Manager role from the user, select the User-Manager role in the Assigned Roles box and click <<Remove selected.

2.6. Delete users

If users should no longer have access to the cloud, you can delete them.

To do this, switch to the Users area:

_Users_ area
Figure 13. Users area

Show existing users with View all users:

List of users
Figure 14. List of users

or search specifically for a user using the Search box.

Click on the Delete in the list of users to delete the user.

Alternatively, you can delete the user in the detail view via the icon:

Delete icon
Figure 15. Delete per icon

The user will be permanently deleted after confirming the security prompt:

Confirmation prompt
Figure 16. Confirmation prompt when deleting a user

2.7. Collaboration with partner companies

To simplify user management with partner companies, we use a mechanism called "federation".
This mechanism enables the realization of authentication and authorization across company boundaries.

Important: Each user may only exist once in the system.
Usually, partner companies manage their users (e.g. developers) in a separate realm.
By using a federation, users can be used in several realms, e.g. users of the partner company in your customer realm.

One advantage of the federation - if the user no longer works for the partner, for example, the partner deletes the user and thus removes access to the systems of all customers for whom the user was working at the same time.
In this case, the customer does not need to be informed.

In order to allow users of a partner company access to your customer systems, a federation must be created by e-Spirit. To do this, please contact e-Spirit TechnicalSupport, via

and please inform TechnicalSupport which partner company(ies) should have access to your systems.

Once the federation has been created, you still need to authorize the users of the partner company in your realm and in FirstSpirit projects.
This is done via the assignment of groups.
Only then will the partner company get access.
Without group assignment, federated partner companies can already log in via SSO, but have no access to FirstSpirit.

3. Glossary

AD

Microsoft Active Directory, directory service under Microsoft Windows through which user permissions can be mapped

Azure

Microsoft Azure; efficiently manage access to enterprise applications and role assignments.

Federation

Mechanism which enables the realization of authentication and authorization across company boundaries.

IdP

Identity Provider, software for managing digital identities, e.g., Microsoft Azure

Keycloak

Open source software from Red Hat for managing digital identities and permissions

LDAP

Lightweight Directory Access Protocol; protocol for providing a central location for authentication

OIDC

OpenID Connect; protocol

SAML

Security Assertion Markup Language; protocol that allows identity providers (IdP) to pass authorization data to service providers (SP)

SSO

Single Sign-on, access method to several applications, where the user only has to log in once

This document FirstSpirit Cloud User Management is a product of e-Spirit AG, Dortmund, Germany.
Only a license agreed upon with e-Spirit AG is valid for using all products of e-Spirit.

5. Help

The Technical Support of the e-Spirit AG provides expert technical support covering any topic related to the FirstSpirit™ product. You can get and find more help concerning relevant topics in our community.

6. Disclaimer

This document is provided for information purposes only. e-Spirit may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. e-Spirit specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.