providers/SCIM: customizable externalId, document behavior (#4868)

* only set externalId if mapping hasn't set it

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* better document use of SCIM in conjunction with OAuth/SAML

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

---------

Signed-off-by: Jens Langhammer <jens@goauthentik.io>
This commit is contained in:
Jens L 2023-03-08 00:15:16 +01:00 committed by GitHub
parent 34f01d3731
commit 6ae2fc9668
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 18 additions and 2 deletions

View File

@ -76,6 +76,7 @@ class SCIMGroupClient(SCIMClient[Group, SCIMGroupSchema]):
scim_group = SCIMGroupSchema.parse_obj(delete_none_keys(raw_scim_group))
except ValidationError as exc:
raise StopSync(exc, obj) from exc
if not scim_group.externalId:
scim_group.externalId = str(obj.pk)
users = list(obj.users.order_by("id").values_list("id", flat=True))

View File

@ -63,6 +63,7 @@ class SCIMUserClient(SCIMClient[User, SCIMUserSchema]):
scim_user = SCIMUserSchema.parse_obj(delete_none_keys(raw_scim_user))
except ValidationError as exc:
raise StopSync(exc, obj) from exc
if not scim_user.externalId:
scim_user.externalId = str(obj.uid)
return scim_user

View File

@ -42,3 +42,17 @@ SCIM defines multiple optional features, some of which are supported by the SCIM
- Patch updates
If the service provider supports patch updates, authentik will use patch requests to add/remove members of groups. For all other updates, such as user updates and other group updates, PUT requests are used.
### Using in conjunction with other providers
A lot of applications support SCIM in conjunction with another SSO protocol like OAuth/OIDC or SAML. With default settings, the unique user IDs in SCIM and other protocols are identical, which should easily allow applications to link users the are provisioned with users that are logging in.
Applications can either match users on a unique ID sent by authentik called `externalId`, by their email or username.
#### OAuth/OIDC
The default provider configuration for the _Subject mode_ option of _Based on the User's hashed ID_ matches the `externalId` that's generated by default. If any other _Subjet mode_ is selected, the `externalId` attribute can be customized via SCIM mappings.
#### SAML
The SAML NameID policy _urn:oasis:names:tc:SAML:2.0:nameid-format:persistent_ uses the same unique user identifier as the default `externalId` value used by the SCIM provider. If a SAML application does not send a NameID request, this value is also used as fallback.