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
The group name testcustomer-git-user follows from

• the customer name testcustomer
• and the suffix denoting access rights git-user.

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 rights are managed centrally in Keycloak for both FirstSpirit and other applications that are part of the FirstSpirit ecosystem, such as Git, Bamboo, and Artifactory.

• Permissions for FirstSpirit: In the FirstSpirit Cloud, access permissions cannot generally be assigned via roles. Permissions for accessing FirstSpirit are assigned exclusively via groups. To do this, you must configure external groups in the respective FirstSpirit project that are mapped to groups in Keycloak. For more information, see Creating External Groups in a FirstSpirit Project.
• Permissions for other applications: Permissions for accessing Git, Bamboo, and Artifactory are granted directly in Keycloak via groups.
• Roles in Keycloak: Access rights for FirstSpirit and other applications are granted via groups. The exceptions are the two Keycloak roles, User-Manager and password-user. These roles are not FirstSpirit or application roles. However, the password-user role has an indirect effect on FirstSpirit access; see password-user role.

User-Manager role

In Keycloak, a user with the role 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. FirstSpirit'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.

password-user role

The password-user role controls which users can set a local password in Keycloak and use it to authenticate locally. A local password is independent of the password from an external identity provider and is required for technical use cases where browser-based SSO authentication is not possible, such as with FirstSpirit CLI or direct API authentication.

Regardless of whether you use an IdP, all users are assigned the password-user role by default through the default roles. If, after setting up an IdP connection, you want to restrict the ability to assign local passwords to your users, contact FirstSpirit Support to have the role removed from the default roles. Afterward, the User-Manager can assign the role to specific users or groups as needed.

If a user's password-user role is revoked, that user can no longer set or change a local password. In addition, local authentication is no longer possible, even if a password has already been stored. An existing SSO login via the IdP is not affected by this.

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 FirstSpirit 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 FirstSpirit.

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.

Protocols: OIDC & SAML

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 FirstSpirit and assigned 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 support@rezolve.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

As soon as the first user is set up, FirstSpirit will confirm your request via email.

You must first activate the user account:

• Go to the account URL for your environment, for example, https://<customer_name>-account.e-spirit.hosting.
  If you are using a partner realm that does not have FirstSpirit systems, please use the central URL; see the info box below.
• Click Forgot Password.
  
• Enter the email address that was registered with FirstSpirit for the first user.

You will receive a verification email:

• Click the link in the email.
  → You will be redirected to your Keycloak account page.
• Set a password under Account security > Signing in.

The first user has been set up. The first user is assigned the User-Manager role and can add and manage additional 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 the button under Or sign in with (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.

You can use the following e-mail template as the basis for your own e-mail and customize it as you see fit:

User: Activating Your Account

The user must activate their newly created account on their own. Notify the user of the steps required to do so:

• Go to the account URL for your environment, for example, https://<customer_name>-account.e-spirit.hosting.
• Click Forgot Password.
  
• Enter the email address that was registered with FirstSpirit for the first user.

You will receive a verification email:

• Click the link in the email.
  → You will be redirected to your Keycloak account page.
• Set a password under Account security > Signing in.

The user account has been set up. The user can now log in to 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.

Assigning 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.

Assigning the password-user role

As a user manager, you can assign the password-user role to a user to enable local authentication.

In Keycloak:

• Navigate to the section Users.
• Open the details view for the desired user and go to the Role Mapping tab.
• Click Assign role" and select Realm role."
• Select the "password-user" role.

The role can also be assigned to a group. To do this, go to the Groups section, open the details view for the desired group, and follow the same procedure.

Configuring external groups in FirstSpirit projects

Keycloak and FirstSpirit are connected through groups with matching group names. The groups must be created in the respective FirstSpirit projects and marked as external. Activities in Keycloak, such as creating or renaming groups, are not automatically transferred to FirstSpirit. The assignment of users to groups occurs exclusively in Keycloak.

• 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.

Creating a federation needs to be requested by the customer with the FirstSpirit Support. The partner company cannot request to create a federation.

Place your support request with support@rezolve.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 a 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 support@rezolve.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 FirstSpirit

OIDC

• Set up your IdP using the received redirect URI.
• Inform FirstSpirit 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 FirstSpirit 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

FirstSpirit prefers the OIDC protocol. No support can be provided for setting up the SAML configuration in Azure Cloud.

IdP definition in the FirstSpirit Cloud

The IdP in the FirstSpirit Cloud is defined by FirstSpirit.

You will be notified by FirstSpirit 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.