FirstSpirit Cloud: user management and access management
About this document
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:
User management and access rights
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.
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).
Realms, users, groups, rights
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.
Realms are central organizational tools for access rights management. A realm is a configuration unit in which data records of
- 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.
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 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.
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.
"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.
"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.
"testcustomer-users-prod": users must belong to the "testcustomer-users-prod" group to work in the productive environment.
The functions and permissions of further default groups are pre-configured and can be adapted project-specifically if required.
Editors with extended permissions: direct content release, editing permissions and user permission assignment, maintenance of certain menu items.
FirstSpirit template developers: configuring templates, Git access (changes in source code).
Classic editors: viewing all content, editing specific content. No release permissions.
Project administrators for the development environment: setting FirstSpirit group permissions, setting languages and background process flows to update websites.
Project administrators for the QA environment.
Project administrators for the productive environment: managing publicly available websites.
Permissions to transfer project templates from the development environment to the QA environment and on to the productive environment.
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.
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.
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:
For details, see Managing users.
External Identity Provider
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.
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.
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.
Managing users in Keycloak
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 firstname.lastname@example.org 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:
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.
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.
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
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.
- Username (mandatory field)
- 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.
we’ve created your account for the
To sign in, you have to activate your account first:
1. Please open the URL https://accounts.e-spirit.cloud/
2. Please enter this e-mail address, which represents your FirstSpirit user name.
3. Afterwards you will receive an e-mail to set your password (please check your spam folder, just in case the confirmation e-mail got delivered there instead of your inbox)
After setting the password your account is activated. No further e-mail will be sent!
The stages can be reached via following URLs:
* Development (DEV) http://
* Quality Assurance (QA) http://
* Production (PROD) http://
If you have any questions, please feel free to contact me.
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.
It is not possible to restore a deleted user with the original settings.
It is not possible to delete users that are not managed by your company (e.g. users from partner organizations or Crownpeak employees).
For user control:
- Deleting user from associated user groups
- Deleting associated user groups
- Support Request to delete the entire partner realm
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 email@example.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.
Connecting an Identity Provider
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.
- It is necessary to add the IdP connection with SAML by adding an application ID URI in the form
Consult your Azure AD administrator before taking further steps with setting up SAML.
- If this condition cannot be met, you can only connect your IdP with OIDC.
Creating Support request
- about your intention to connect your FirstSpirit Cloud to your IdP;
- about the connection protocol to be used.
We will prepare your FirstSpirit Cloud for the IdP integration and send you links that you need for the preparation in your IdP:
- You will receive a Redirect URI
- Setting up the IdP with OIDC.
- You will receive an Application ID URI
- 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.
Setting up IdP
- 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
- 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
- E-mail address to set up the User Manager role
- 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.
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.
Template: FirstSpirit Cloud user login with 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.
- 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.