Skip to content

Commit a4bfe42

Browse files
ThibHrrdsebferrer
ThibHrrd
and
sebferrer
committed
feat(saml): saml 2.0 implementation
Signed-off-by: ThibaultHerard <thibaultherard10@gmail.com> Co-authored-by: sebferrer <sebferrer@users.noreply.github.com>
1 parent f82684b commit a4bfe42

File tree

4 files changed

+227
-0
lines changed

4 files changed

+227
-0
lines changed

‎docs/kratos/sso-signin/01_overview.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: overview
3+
title: Set up SSO and connect with SAML providers
4+
sidebar_label: Overview
5+
---
6+
7+
# Get started with SSO
8+
9+
When using Kratos in a company, it is possible to use it as a SAML Service Provider and connect it to a SAML Identity Provider
10+
like [ADFS](./10_adfs.mdx) or other [Generic Identity Providers](./05_generic.mdx) IDPs.

‎docs/kratos/sso-signin/05_generic.mdx‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
id: generic
3+
title: Add any SAML SSO provider to your Ory project
4+
sidebar_label: Generic provider
5+
toc_max_heading_level: 4
6+
---
7+
8+
# Generic provider
9+
10+
The "Generic Provider" option allows you to add any SAML provider that doesn't require custom API calls to get the required user
11+
information. To add a SAML SSO provider, you need these details:
12+
13+
- Service provider metadata
14+
15+
````mdx-code-block
16+
import Tabs from '@theme/Tabs';
17+
import TabItem from '@theme/TabItem';
18+
19+
<Tabs>
20+
<TabItem value="cli" label="Ory CLI">
21+
22+
Follow these steps to add a generic provider as a SAML SSO provider to your project using the Ory CLI:
23+
24+
1. Get your provider metadata.
25+
2. Create a [Jsonnet code snippet](#data-mapping) to map the desired claims to the Ory Identity schema.
26+
3. Encode the Jsonnet snippet with [Base64](https://www.base64encode.org/) or host it under an URL accessible to The Ory Network.
27+
4. Download the Ory Identities config from your project and save it to a file:
28+
29+
```shell
30+
## List all available projects
31+
ory list projects
32+
33+
## Get config
34+
ory get identity-config {project-id} --format yaml > identity-config.yaml
35+
```
36+
5. Add the SAML SSO provider configuration to the downloaded config. Add the Jsonnet snippet with mappings as a Base64
37+
string or provide an URL to the file.
38+
39+
```yaml
40+
selfservice:
41+
methods:
42+
saml:
43+
config:
44+
providers:
45+
- id: generic # This is `<provider-id>` in the Authorization callback URL. DO NOT CHANGE IT ONCE SET!
46+
label: generic # Used as a label for the UI login button
47+
provider: generic
48+
public_cert_path: .... # Replace this with the provider public certificate path
49+
private_key_path: .... # Replace this with the provider private key path
50+
mapper_url: "base64://{YOUR_BASE64_ENCODED_JSONNET_HERE}"
51+
52+
idp_information:
53+
idp_metadata_url: .... # Replace this with identity provider path URL
54+
55+
# You must match the values required by Kratos with the name of the attributes sent in the SAML assertion
56+
attributes_map:
57+
id: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn # ADFS example
58+
firstname: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname # ADFS example
59+
lastname: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname # ADFS example
60+
nickname: default
61+
gender: default
62+
birthdate: default
63+
picture: default
64+
email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress # ADFS example
65+
roles: http://schemas.microsoft.com/ws/2008/06/identity/claims/role # ADFS example
66+
phone_number: default
67+
enabled: true
68+
```
69+
70+
6. Update the Ory Identities configuration using the file you worked with:
71+
72+
```shell
73+
ory update identity-config {project-id} --file updated_config.yaml
74+
```
75+
76+
</TabItem>
77+
</Tabs>
78+
````

‎docs/kratos/sso-signin/10_adfs.mdx‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
id: adfs
3+
title: Add an ADFS as a SAML SSO provider in Ory
4+
sidebar_label: ADFS
5+
toc_max_heading_level: 4
6+
---
7+
8+
# Active Directory Federation Services
9+
10+
:::note
11+
12+
To add an ADFS as a SAML SSO provider, you need a ADFS installed in a Windows Server.
13+
14+
:::
15+
16+
````mdx-code-block
17+
import Tabs from '@theme/Tabs';
18+
import TabItem from '@theme/TabItem';
19+
20+
<Tabs>
21+
<TabItem value="cli" label="Ory CLI">
22+
23+
Follow these steps to add an ADFS as a SAML SSO provider to your project using the Ory CLI:
24+
25+
1. In the top bar of your Windows Server, click on **Tools** → **AD FS Management**.
26+
2. Click on **Relying Party Trusts**.
27+
3. Click on **Add Relying Party Trust...***.
28+
4. Select **Claims aware** then click on **Start**.
29+
5. Select **Import data about the relying party from a file** and select your Kratos SAML metadata file.
30+
6. Then click the **Next** button.
31+
7. Enter a display name for the relying party and click the **Next** button.
32+
8. Click **Next** in the Access Control window.
33+
9. Click **Next** again to proceed.
34+
10. Click the **Close** button in the last window. Your relying party trust is now added to your ADFS.
35+
11. Create a Jsonnet code snippet to map the desired claims to the Ory Identity schema.
36+
37+
```jsonnet
38+
local claims = {
39+
email_verified: true,
40+
} + std.extVar('claims');
41+
42+
{
43+
identity: {
44+
traits: {
45+
[if 'email' in claims && claims.email_verified then 'email' else null]: claims.email,
46+
first_name: claims.given_name,
47+
last_name: claims.family_name,
48+
[if 'hd' in claims && claims.email_verified then 'hd' else null]: claims.hd,
49+
},
50+
},
51+
}
52+
```
53+
54+
The sample Jsonnet snippet creates the following mapping:
55+
56+
| ADFS claim | Ory Identity schema mapping |
57+
| :----------- | :-------------------------- |
58+
| email | email |
59+
| given_name | first_name |
60+
| family_name | last_name |
61+
62+
:::note
63+
64+
If you want to use this data mapping, you must include the `first_name` and `last_name` fields in your Identity Schema
65+
66+
:::
67+
68+
3. Encode the Jsonnet snippet with [Base64](https://www.base64encode.org/) or host it under an URL accessible to The Ory Network.
69+
70+
```shell
71+
cat your-data-mapping.jsonnet | base64
72+
```
73+
74+
4. Download the Ory Identities config from your project and save it to a file:
75+
76+
```shell
77+
## List all available projects
78+
ory list projects
79+
80+
## Get config
81+
ory get identity-config {project-id} --format yaml > identity-config.yaml
82+
```
83+
84+
5. Add the SAML SSO provider configuration to the downloaded config. Add the Jsonnet snippet with mappings as a Base64
85+
string or provide an URL to the file.
86+
87+
```yaml
88+
selfservice:
89+
methods:
90+
saml:
91+
config:
92+
providers:
93+
- id: generic # This is `<provider-id>` in the Authorization callback URL. DO NOT CHANGE IT ONCE SET!
94+
label: generic # Used as a label for the UI login button
95+
provider: generic
96+
public_cert_path: .... # Replace this with the provider public certificate path
97+
private_key_path: .... # Replace this with the provider private key path
98+
mapper_url: "base64://{YOUR_BASE64_ENCODED_JSONNET_HERE}"
99+
100+
idp_information:
101+
idp_metadata_url: .... # Replace this with identity provider path URL
102+
103+
# You must match the values required by Kratos with the name of the attributes sent in the SAML assertion
104+
attributes_map:
105+
id: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn # ADFS example
106+
firstname: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname # ADFS example
107+
lastname: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname # ADFS example
108+
nickname: default
109+
gender: default
110+
birthdate: default
111+
picture: default
112+
email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress # ADFS example
113+
roles: http://schemas.microsoft.com/ws/2008/06/identity/claims/role # ADFS example
114+
phone_number: default
115+
enabled: true
116+
```
117+
118+
6. Update the Ory Identities configuration using the file you worked with:
119+
120+
```shell
121+
ory update identity-config {project-id} --file updated_config.yaml
122+
```
123+
124+
</TabItem>
125+
</Tabs>
126+
````

‎src/sidebar.js‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,19 @@ module.exports = {
9292
"kratos/social-signin/account-linking",
9393
],
9494
},
95+
{
96+
type: "category",
97+
label: "SSO sign-in",
98+
items: [
99+
"kratos/sso-signin/overview",
100+
{
101+
"Integrating providers": [
102+
"kratos/sso-signin/generic",
103+
"kratos/sso-signin/adfs",
104+
],
105+
},
106+
],
107+
},
95108
"identities/sign-in/check-session",
96109
"identities/sign-in/actions",
97110
],

0 commit comments

Comments
 (0)