Foundation Keycloak Advanced¶

Setup¶

The steps below describe how to configure keycloak to foundation:

• Realm
  • Email
  • Themes
• Clients
  • Client to authentication
  • Client for tenant
  • Clients roles to access URI
    • Foundation certificates
    • Foundation admin
• Adding roles to the user role mapping
• LDAP configuration
• SSO
• Truststore

Realm¶

Once you have an administrative account for the Admin Console, you can configure realms. A realm is a space where you manage objects, including users, applications, roles, and groups. A user belongs to and logs into a realm. One Keycloak deployment can define, store, and manage as many realms as there is space for in the database.

Realm feature, see keycloak realm.

Email¶

Keycloak sends emails to users to verify their email addresses, when they forget their passwords, or when an administrator needs to receive notifications about a server event. To enable Keycloak to send emails, you provide Keycloak with your SMTP server settings.

For more information, see Keycloak Email.

Procedure

1. Click "Realm settings" in the menu.

2. Click the "Email" tab.

   

3. Fill in the fields and toggle the switches as needed.

Themes¶

Keycloak provides theme support for web pages and emails.

Procedure

Default theme¶

1. Select Realm.

2. Click "Realm Settings" in the menu.

3. Click the "Themes" tab.

4. Select synchro theme available themes box.

   login-page-sso-buttons-only.png

Login page with synchro theme

SSO/OIDC Buttons only at login page¶

1. Select Realm.

2. Click "Realm Settings" in the menu.

3. Click the "Themes" tab.

4. Select synchro_sso_only theme available themes box.

   

Login page with synchro sso/oidc buttons only theme

Clients¶

Clients are entities that can request Keycloak to authenticate a user or get roles information.

Procedure

1. Click "Clients" in the menu.

2. Click "Create".

3. Create a Client ID following the Pattern:

   Example for Client ID:

   Pattern: <tenant>-<environment>

   TenantID: SYNCHRODESENVOLVIMENTO

   Environment: desenvolvimento

   Client ID: synchro-desenvolvimento

   Check available environment default list.

   Client feature, see keycloak client.

4. Save.

   

Client to authentication¶

Procedure

1. At Client Settings Tab in General Settings fill client id field with the client ID name, we suggest foundation-authentication

2. Insert a "Valid Redirect URIs", In Access settings group the default value for Valid redirect URLs is http://*, https://*:

   Required field. Enter a URL pattern and click + to add and - to remove existing URLs and click Save. You can use wildcards at the end of the URL pattern.

   Security advise

   Using the default values http://* and https://* makes your keycloak client accepts authentications redirects to all url protocols and adresses. It's a full wild card settings. To make your enviroment more secure we recommend edit this values to accept only recirects came from specifics foundation servers and protocols.

   See example bellow:

   Generic/Default: http://* and/or https://*

   or

   Specific: http://172.25.0.0/* and/or http://synchro-dev/*

   Basic settings, see Keycloak Basic configuration.

   

3. Enable "Client authentication", "Service Accounts roles" and "Direct access grants" properties at Capibility Config group.

   

4. Assign realm-admin role to "Service Accounts roles"

   4.1. Click in "Assign Role" 4.2. Select "realm-admin" roles and click in "Assign"

5. Active foundation-authentication-dedicated full scope.

   5.1. Click in "foundation-authentication-dedicated" 5.2. Go to Scope tab, then active Full scope allowed toggle

6. Save.

7. Click the "Credentials" tab, now there is a secret.

   

8. To configure client authentication in foundation:

   8.1. Change keycloak information

Client for tenant¶

If your environment is Multitenancy, create a client for each Tenant.

Procedure

1. See creating a client.

2. See creating a client roles applications

Clients roles application¶

Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution. Clients can also be entities that just want to request identity information or an access token so that they can securely invoke other services on the network that are secured by Keycloak.

All Clients needs this role to access application URI

Procedure

1. Click "Clients" in the menu.

2. Select your client.

3. Click the "Roles" tab, and "Create role" button.

4. Add a role following the pattern.

   See example bellow:

   Pattern: <clientID>-<application>

   Client ID: synchro-desenvolvimento

   application: foundation

   Result: synchro-desenvolvimento-foundation

   Role mapping feature, see Restrict user role mapping.

   

5. If this client needs open foundation administration console, see foundation admin.

Foundation certificates¶

Foundation need a clients role FOUNDATION_CERTIFICATES to update Keystore administration console.

Foundation admin¶

Foundation need a clients role FOUNDATION_ADMIN to open administration console.

Adding roles to the user¶

You can assign role mappings to a user through the Role Mappings tab for that user.

Procedure

1. Click "Users" in the menu.

2. Click the user that you want to assigning a role. If the user is not displayed, click View all users or search the user by mail at the search field.

3. Click the "Role Mapping" tab.

4. Click the "Assign role" button.

5. Select "Filter by clients" and search by role name.

   

6. Selected roles that you want and click "Assign" button.

7. Do user Logout/Login in application to get new roles.

See more, in Keycloak assigning role mappings.

Regenerate Client secret¶

Procedure

1. Click "Clients" in the menu.

2. Select Client.

3. Click the "Credentials" tab.

4. Click the "Regenerate" button.

5. To configure client authentication in foundation:

   5.1. Change keycloak information.

6. Access View.

Change keycloak information¶

sudo foundation config --on-premises-keycloak

INFO[0000] Reading profiles from /etc/foundation/
default

QUESTION: Select your profile file (current: default):

QUESTION: This command changes your keycloak settings to local. Use only if you are an on premise installation. CONTINUE? (y/N): y

Domain name¶

QUESTION: Using domain name in a multitenant solution []:

If you have different tenants: In many multitenant, a domain name is used to identify a tenant.

URL server¶

QUESTION: (Keycloak) URL [http://192.168.0.160/keycloak]:

Realm¶

QUESTION: (Keycloak) Realm [synchro]:

Get Realm name from Realm, see Keycloak Realm

Client ID¶

QUESTION: (Keycloak) Client ID [foundation-authentication]:

Get Client ID from Client authentication, see Keycloak Clients authentication

Client Secret¶

QUESTION: (Keycloak) Client Secret [secret]: B24KXaFbwPkwokBngVyjSp

Get Secret credentials from client authentication, see Keycloak Clients authentication

LDAP configuration¶

1. Click "User Federation" in the menu and "Add Ldap providers".

   

2. Fill all fields like the example below

   

   

   

   

   

3. Save and click "Mappers" tab, to create ldap fields relations, create all relations what you need:

   Mapper list:

   

   Mail relation example:

   

See more details, in Official Keycloak LDAP configuration site.

Valid Redirect URIs¶

The fields for "Valid Redirect URIs", In Access settings at your Keycloak Client to authentication configuration need you attention for more security.

The default values for "Valid redirect URIs" is http://*, https://*:

Using the default values http://* and https://* makes your keycloak client accepts authentications redirects to all uri,protocols and adresses. It's a full wild card settings.

To make your enviroment more secure we recommend edit this values to accept only recirects came from specifics foundation servers and protocols.

Enter a URL pattern and click + to add and - to remove existing URIs and click Save. You can use wildcards at the end of the URI pattern.

For basic settings, see Keycloak Basic configuration.

SSO¶

See more details, in Official Keycloak SSO protocols

Auto Login¶

This is needed when a user would like to go directly to the platform and skip the “login with OIDC SSO or OKTA” page. This can be turned on (or off) by following the below directions:

1. Login to the Keycloak Administration Console
2. Ensure the Synchro Realm is selected
3. In the left-hand-menu, Click on Authentication
4. Under Flows select Browser
5. On the Identity Provider Redirector line, click on Settings 5.1 If you would like to disable (turn off) the auto login - we can 'Clear’ information on the Identity provider redirector line
6. Enter the name of the Identity provider, e.g. oidc, in both the Alias and Default Identity Provider boxes
7. Select Save

Truststore¶

If you need additional certificates, which will be the case if you have self-signed or internal certificate authorities that are not recognized by the Keycloak default JRE, they can be included in the /foundation/system/default/foundation/keycloak/truststore where /foundation should be your configured foundation volume, only truststore accepeted into this directory or subdirectories. The certs may be in PEM files, or PKCS12 files with extension .p12 or .pfx. The certs must be unencrypted - meaning no password is expected. And also root permissions is needed as well if new subdirectories was created within this default directory.