sherpa-core<\/strong> docker container, then restart the container. The content of that file slightly depends on the identity provider (see sub-paragraphs below).<\/p>\n\n\n\nThis should be enough to enable SSO and to map users in the “Default” group of the Kairntech platform with the following roles: “Default annotation components” and “Data analyst”. Those roles are not administrative roles but they will allow using all the features of all projects.<\/p>\n\n\n\n
Microsoft Entra ID<\/h3>\n\n\n\n
Content of the sso.yaml<\/strong> file for Microsoft Entra ID:<\/p>\n\n\n\nsherpa:\n httpserver:\n auth:\n schemes: jwt,basic,oauth2\n oauth2:\n troubleshoot: false\n # replace with the address used to access Kairntech<\/strong>\n appLocation: https:\/\/your.kairntech.host<\/strong>\n provider: AzureAD\n options:\n # replace with the identifier of your EntraID tenant<\/strong>\n tenant: 813e8c6f-12f2-41ef-80d7-544ec1fd701e<\/strong>\n # replace with the identifier of the Kairntech enterprise app<\/strong>\n clientId: 83744636-76be-4777-976c-1a59651a61df<\/strong> \n # replace with the secret of the Kairntech enterprise app<\/strong>\n clientSecret: 6cd7c763-0435-4e51-aa34-8db689d2fdfb<\/strong>\n<\/code><\/pre>\n\n\n\nKeycloak<\/h3>\n\n\n\n
Content of the sso.yaml<\/strong> file for Microsoft Keycloak:<\/p>\n\n\n\nsherpa:\n httpserver:\n auth:\n schemes: jwt,basic,oauth2\n oauth2:\n troubleshoot: false\n # replace with the address used to access Kairntech<\/strong><\/strong>\n appLocation: https:\/\/your.kairntech.host<\/strong>\n provider: Keycloak\n options:\n # replace with the address of your Keycloak server\n<\/strong> site: \"https:\/\/your.keycloak.host<\/strong>\/realms\/{realm}\"\n # replace with the Keycloak realm to be used\n<\/strong> tenant: your-realm<\/strong>\n # replace with the Kairntech Client ID<\/strong>\n clientId: kairntech-app <\/strong>\n # replace with the Kairntech Client Secret<\/strong>\n clientSecret: 6cd7c76304354e51aa348db689d2fdfb<\/code><\/pre>\n\n\n\nUser mapping<\/h2>\n\n\n\n
The Kairntech platform has a user database with users, predefined roles, permissions etc… During the SSO login, the IdP user will be mapped to a Kairntech user into the database.<\/p>\n\n\n\n
You can use the identity returned by the IdP to initialize the following user fields in the Kairntech database:<\/p>\n\n\n\n
\n- username: the identifier of the user<\/li>\n\n\n\n
- profilename: the display name of the user<\/li>\n\n\n\n
- email: the email of the user<\/li>\n\n\n\n
- groups: groups the user is belonging to<\/li>\n\n\n\n
- roles: roles granted to the user<\/li>\n<\/ul>\n\n\n\n
This is done using Jinja 2 snippets operating on the identity (and optionally the profile returned by the Microsoft Graph for Entra ID.<\/p>\n\n\n\n
Here is the default user mapping:<\/p>\n\n\n\n
sherpa:\n httpserver:\n auth:\n oauth2:\n mapping:\n user:\n username.j2.mapping<\/strong>: |\n {% if provider == 'AzureAD' -%}\n {{ identity.oid }}\n {% else -%}\n {{ identity.preferred_username }}\n {% endif -%}\n profilename.j2.mapping<\/strong>: |\n {{ identity.given_name ~ ' ' ~ identity.family_name }}\n email.j2.mapping<\/strong>: | \n {{ identity.email }}\n groups.j2.array.mapping<\/strong>: |\n {% set output = [{'name': 'default' }] -%}<\/code><\/pre>\n\n\n\nYou don’t need to repeat it into your own configuration but you can override some fields.
For instance, if you want to use the displayName coming from the Microsoft Graph, you can create a sso-configuration.yaml<\/strong> file, mount it in the \/app\/kairntech\/sherpa\/conf\/user\/<\/strong> directory of the sherpa-core<\/strong> docker container, then restart the container.<\/p>\n\n\n\nContent of the sso-configuration.yaml<\/strong> file:<\/p>\n\n\n\nsherpa:\n httpserver:\n auth:\n oauth2:\n mapping:\n user:\n profilename.j2.mapping<\/strong>: \"{{ profile.displayName }}\"\n<\/code><\/pre>\n\n\n\nGranting access to Kairntech<\/h2>\n\n\n\n
By default all IdP users will be allowed to connect using SSO because as soon as a user is part of a Kairntech group, they will be allowed to connect and, as show above, SSO users are mapped by default to the “Default” group.<\/p>\n\n\n\n
The first way to deny access to users is to use the “accessDenied” feature. <\/p>\n\n\n\n
For instance you can deny the access to any user that is not a member of a specific Entra ID group using the following configuration fragment:<\/p>\n\n\n\n
sherpa:\n httpserver:\n auth:\n oauth2:\n mapping:\n user:\n accessDenied.j2.boolean.mapping<\/strong>: |\n {%- set output = (profile.memberOf | selectattr(\"id\", \"equalto\", \"d56f7e19-2353-42f9-a288-0e3305dc0cd2Z\") | length ) == 0 -%}<\/code><\/pre>\n\n\n\nHere the SSO user will still be mapped the the “Default” group but it will be denied the access anyway. You can also use group mapping to deny access to users.<\/p>\n\n\n\n
Group mapping<\/h2>\n\n\n\n
As shown above, SSO users are mapped into the Default group of Kairntech by default.<\/p>\n\n\n\n
If you can to leverage IdP groups (only Entra ID groups are supported right now), you will need the following configuration fragment:<\/p>\n\n\n\n
sherpa:\n httpserver:\n auth:\n oauth2:\n profile:\n provider: MicrosoftGraph\n options:\n # in order to get user group membership with MicrosoftGraph\n withGroups: true\n # or... in order to get user group transitive membership\n withTransitiveGroups: true\n<\/code><\/pre>\n\n\n\nExplicit group mapping<\/h3>\n\n\n\n
You can use a more complex Jinja expression to return a different list of groups that will be created if they do not exist. For instance, this configuration file will map two Entra ID groups (matched using their identifiers) to Kairntech groups (named after the displayName of those IdP groups):<\/p>\n\n\n\n
sherpa:\n httpserver:\n auth:\n oauth2:\n mapping:\n user:\n groups.j2.array.mapping<\/strong>: |\n {% set ns = namespace(output=[]) -%}\n {% set idp_group_ids = [ \"b9d6685c-cb22-4875-81d1-3b5ffb6ed313\", \"82e198e1-83d8-431e-b2b1-a8313d0ddae4\" ] -%}\n {% for idp_group_id in idp_group_ids -%}\n {% set idp_group = (profile.memberOf | selectattr('id', 'equalto', idp_group_id) | first) -%}\n {% if idp_group -%}\n {% set ns.output = ns.output + [{'label': idp_group['displayName'], 'identifier': idp_group_id }<\/strong>] -%}\n {% endif -%}\n {% endfor -%}\n {% set output = ns.output -%}<\/code><\/pre>\n\n\n\nThat approach might be useful to bootstrap the initial Kairntech platform administrators: if “b9d6685c-cb22-4875-81d1-3b5ffb6ed313” and “82e198e1-83d8-431e-b2b1-a8313d0ddae4” are identifiers of the “Kairntech Administrators” and “Kairntech Power Users” groups (for instance), then only users belonging to those groups will be allowed to connect to Kairntech. That is because other users will have an empty list of groups and, as mentioned above, one has to be part of a Kairntech group to be able to connect.<\/p>\n\n\n\n
Implicit group mapping<\/h3>\n\n\n\n
Once a Kairntech platform administrator has been allowed to connect using SSO, they can use the Kairntech user administration interface to create a Kairntech group and map it to an IdP group by selecting it in a drop-down list. <\/p>\n\n\n\n
Kairntech administrators might create a “Kairntech Users” groups that is mapped to a “Kairntech Users” IdP group.<\/p>\n\n\n\n
Even if that group is not explicitly mentioned into the user mapping, it is still possible to map it by using the “attach existing groups” feature that is activated by the following configuration snippet:<\/p>\n\n\n\n
sherpa:\n httpserver:\n auth:\n oauth2:\n mapping:\n attachExistingGroups: true<\/code><\/pre>\n\n\n\nWhen activated, any SSO user who is a member of an IdP group that has already been mapped to a Kairntech group will be allowed to connect, even if the group is not mentioned into the groups.j2.array.mapping<\/strong> field of the mapping.<\/p>\n\n\n\nRole mapping<\/h2>\n\n\n\n
The Kairntech platform is providing many predefined roles and permissions. If generally requires many roles to provide the desired features to a user.<\/p>\n\n\n\n
It is possible to map IdP application roles and IdP groups to Kairntech roles. The default mapping is defined as followed:<\/p>\n\n\n\n
sherpa:\n httpserver:\n auth:\n oauth2:\n mapping:\n roles:\n # using client app roles and identity provider groups\n source: [ app_roles, idp_groups ]\n # set independently of client app roles or provider groups\n base: [ __DefaultAnnotationComponents ]\n # set if no client app role or no identity provider group found\n default: [ __ProjectManager ]<\/code><\/pre>\n\n\n\nYou can map an IdP group or an application role using the following syntax:<\/p>\n\n\n\n
sherpa:\n httpserver:\n auth:\n oauth2:\n mapping:\n roles:\n # using client app roles and identity provider groups\n source: [ app_roles, idp_groups ]\n # set independently of client app roles or provider groups\n base: [ __DefaultAnnotationComponents ]\n # the \"Kairntech Administrators\" IdP group:\n b9d6685c-cb22-4875-81d1-3b5ffb6ed313:\n - PlatformProjectAdmin # can see all projects of all groups\n - PlatformUserAdmin # can see all groups and users\n - __ProjectManager # can use all features \n # a \"Kairntech Administrator\" app role:\n KairntechAdmin:\n - PlatformProjectAdmin # can see all projects of all groups\n - PlatformUserAdmin # can see all groups and users\n - __ProjectManager # can use all features \n # set if no client app role or no identity provider group found\n default: [ __Evaluator ]<\/code><\/pre>\n\n\n\nThat mapping states that any member of the “Kairntech Administrators” IdP group will be granted the following roles:<\/p>\n\n\n\n
![\"\"](\"https:\/\/kairntech.com\/doc\/wp-content\/uploads\/sites\/2\/2024\/12\/image.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/kairntech.com\/doc\/wp-content\/uploads\/sites\/2\/2024\/12\/image-1.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/kairntech.com\/doc\/wp-content\/uploads\/sites\/2\/2024\/12\/image-2-1024x389.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/kairntech.com\/doc\/wp-content\/uploads\/sites\/2\/2024\/12\/image-3-1024x254.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/kairntech.com\/doc\/wp-content\/uploads\/sites\/2\/2024\/12\/image-4.png\")
<\/figure>\n\n\n\n