Skip to content

Commit b5cf696

Browse files
himeshsiriwardanahimeshsiriwardana
authored
Merge pull request #6025 from ImalshaD/fix-acr-amr-missing-docs-in-7.x.x
Add ACR-AMR docs
2 parents 17a840b + 3da87b7 commit b5cf696

8 files changed

Lines changed: 588 additions & 4 deletions

File tree

‎en/identity-server/7.0.0/docs/guides/authentication/conditional-auth/acr-and-amr.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# ACR and AMR
2+
3+
Authentication Context Class Reference (ACR) and Authentication Method Reference (AMR) are standard parameters used in OIDC and SAML authentication flows to convey assurance levels and authentication method details.
4+
5+
## What is ACR?
6+
7+
ACR is an optional parameter used in SAML and OIDC authentication requests. It enables applications to communicate the required level of assurance to {{product_name}}, which then enforces the appropriate authentication steps. In certain contexts, ACR is also referred to as the Level of Assurance (LoA).
8+
9+
ACR values are flexible and can be custom-defined, as long as both the application and {{product_name}} agree on their meaning.
10+
11+
## What is AMR?
12+
13+
AMR provides information about the authentication methods that were used to assert a user's authenticity. It records the session activities that took place while authenticating a user.
14+
15+
By default, {{product_name}} uses the internal names of the authenticators as AMR values (e.g., `BasicAuthenticator`, `totp`). You can configure mappings to translate these to standard values — see [Translate AMR values](#translate-amr-values).
16+
17+
## ACR vs AMR
18+
19+
While ACR denotes the set of business rules that must be met during authentication, AMR denotes the authentication methods that were actually used to meet those rules.
20+
21+
For example:
22+
23+
- An application requests `acr2` (high assurance) → {{product_name}} enforces MFA based on the configured authentication script.
24+
- The resulting ID token's `amr` claim reflects the actual methods used: e.g., `["BasicAuthenticator", "totp"]`.
25+
26+
## ACR and AMR in authentication responses
27+
28+
After a successful authentication, both `acr` and `amr` are included in the ID token. The following is an example of a decoded ID token:
29+
30+
```json
31+
{
32+
"at_hash": "6OXwfxJaTWYC56RccEhSJg",
33+
"aud": "EUVvhKM28RkwTQL9A52kqXnfCj8a",
34+
"acr": "LOA2",
35+
"c_hash": "lDj9nihZGSUmgNmz_lxxXA",
36+
"sub": "admin",
37+
"nbf": 1548396413,
38+
"azp": "EUVvhKM28RkwTQL9A52kqXnfCj8a",
39+
"amr": [
40+
"BasicAuthenticator",
41+
"totp"
42+
],
43+
"iss": "https://localhost:9443/oauth2/token",
44+
"exp": 1548400013,
45+
"iat": 1548396413
46+
}
47+
```
48+
49+
For SAML applications, the selected ACR value is returned in the `AuthnStatement` element of the SAML assertion:
50+
51+
```xml
52+
<saml2:AuthnStatement AuthnInstant="2019-07-03T10:26:56.645Z"
53+
SessionIndex="9e2a915b-aa69-4262-bd06-59e70c18469b">
54+
<saml2:AuthnContext>
55+
<saml2:AuthnContextClassRef>urn:federation:authentication:windows</saml2:AuthnContextClassRef>
56+
</saml2:AuthnContext>
57+
</saml2:AuthnStatement>
58+
```
59+
60+
## Translate AMR values
61+
62+
By default, the `amr` claim in the ID token contains the internal names of the authenticators used during authentication (e.g., `BasicAuthenticator`, `totp`). You can translate these to standard [RFC 8176](https://www.rfc-editor.org/rfc/rfc8176){:target="_blank"} AMR values (e.g., `pwd`, `otp`, `hwk`) by configuring {{product_name}}.
63+
64+
You can also suppress a specific authenticator from appearing in the `amr` claim entirely.
65+
66+
### Configure AMR value mappings
67+
68+
Add the following configuration to the `deployment.toml` file found in the `<IS_HOME>/repository/conf/` directory:
69+
70+
!!! note
71+
The `amr_value` should either follow the [RFC 8176 AMR specification](https://www.rfc-editor.org/rfc/rfc8176){:target="_blank"} or be any custom value you prefer to use in the `amr` claim.
72+
73+
```toml
74+
[[authentication_context.method_refs]]
75+
method = "<authenticator_name>"
76+
amr_value = "<amr_value>"
77+
```
78+
79+
The following table describes the configuration parameters:
80+
81+
| Parameter | Type | Description |
82+
|---|---|---|
83+
| `method` | String | The internal name of the authenticator as registered in {{product_name}}. |
84+
| `amr_value` | String | The AMR value to include in the ID token for the given authenticator. |
85+
| `excluded_methods` | Array of strings | Authenticators to exclude from the `amr` claim in the ID token. |
86+
87+
To prevent a specific authenticator from appearing in the `amr` claim of the ID token, use `excluded_methods`:
88+
89+
```toml
90+
[[authentication_context.method_refs]]
91+
excluded_methods = ["<authenticator_name>"]
92+
```
93+
94+
**Example:**
95+
96+
```toml
97+
[[authentication_context.method_refs]]
98+
method = "BasicAuthenticator"
99+
amr_value = "pwd"
100+
101+
[[authentication_context.method_refs]]
102+
method = "DemoFingerprintAuthenticator"
103+
amr_value = "fpt"
104+
105+
[[authentication_context.method_refs]]
106+
method = "DemoFaceIdAuthenticator"
107+
amr_value = "user"
108+
109+
[[authentication_context.method_refs]]
110+
method = "DemoHardwareKeyAuthenticator"
111+
amr_value = "hwk"
112+
113+
[[authentication_context.method_refs]]
114+
excluded_methods = ["AuthenticatorToBeHiddenFromAMR"]
115+
```
116+
117+
### Example: Translated AMR values in ID token
118+
119+
After configuring the mappings, the `amr` claim in the ID token will reflect the translated values:
120+
121+
```json
122+
{
123+
"at_hash": "6OXwfxJaTWYC56RccEhSJg",
124+
"aud": "EUVvhKM28RkwTQL9A52kqXnfCj8a",
125+
"acr": "LOA3",
126+
"c_hash": "lDj9nihZGSUmgNmz_lxxXA",
127+
"sub": "admin",
128+
"nbf": 1548396413,
129+
"azp": "EUVvhKM28RkwTQL9A52kqXnfCj8a",
130+
"amr": [
131+
"pwd",
132+
"hwk",
133+
"user"
134+
],
135+
"iss": "https://localhost:9443/oauth2/token",
136+
"exp": 1548400013,
137+
"iat": 1548396413
138+
}
139+
```
140+
141+
## Next steps
142+
143+
- [Configure ACR-based adaptive authentication]({{base_path}}/guides/authentication/conditional-auth/acr-based-adaptive-auth/)
144+
- [Conditional authentication API reference]({{base_path}}/references/conditional-auth/api-reference/)

‎en/identity-server/7.0.0/mkdocs.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -557,7 +557,9 @@ nav:
557557
- Add adaptive MFA:
558558
- Add adaptive MFA: guides/authentication/conditional-auth/adaptive-mfa.md
559559
- MFA based on user role: guides/authentication/conditional-auth/role-based-template.md
560-
- MFA based on auth context: guides/authentication/conditional-auth/acr-based-adaptive-auth.md
560+
- MFA based on auth context:
561+
- Overview: guides/authentication/conditional-auth/acr-and-amr.md
562+
- Configure ACR-based adaptive authentication: guides/authentication/conditional-auth/acr-based-adaptive-auth.md
561563
- MFA based on user store: guides/authentication/conditional-auth/user-store-based-template.md
562564
- MFA based on login-attempts: guides/authentication/conditional-auth/login-attempt-based-template.md
563565
- MFA based on user group: guides/authentication/conditional-auth/group-based-template.md

‎en/identity-server/7.1.0/docs/guides/authentication/conditional-auth/acr-and-amr.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# ACR and AMR
2+
3+
Authentication Context Class Reference (ACR) and Authentication Method Reference (AMR) are standard parameters used in OIDC and SAML authentication flows to convey assurance levels and authentication method details.
4+
5+
## What is ACR?
6+
7+
ACR is an optional parameter used in SAML and OIDC authentication requests. It enables applications to communicate the required level of assurance to {{product_name}}, which then enforces the appropriate authentication steps. In certain contexts, ACR is also referred to as the Level of Assurance (LoA).
8+
9+
ACR values are flexible and can be custom-defined, as long as both the application and {{product_name}} agree on their meaning.
10+
11+
## What is AMR?
12+
13+
AMR provides information about the authentication methods that were used to assert a user's authenticity. It records the session activities that took place while authenticating a user.
14+
15+
By default, {{product_name}} uses the internal names of the authenticators as AMR values (e.g., `BasicAuthenticator`, `totp`). You can configure mappings to translate these to standard values — see [Translate AMR values](#translate-amr-values).
16+
17+
## ACR vs AMR
18+
19+
While ACR denotes the set of business rules that must be met during authentication, AMR denotes the authentication methods that were actually used to meet those rules.
20+
21+
For example:
22+
23+
- An application requests `acr2` (high assurance) → {{product_name}} enforces MFA based on the configured authentication script.
24+
- The resulting ID token's `amr` claim reflects the actual methods used: e.g., `["BasicAuthenticator", "totp"]`.
25+
26+
## ACR and AMR in authentication responses
27+
28+
After a successful authentication, both `acr` and `amr` are included in the ID token. The following is an example of a decoded ID token:
29+
30+
```json
31+
{
32+
"at_hash": "6OXwfxJaTWYC56RccEhSJg",
33+
"aud": "EUVvhKM28RkwTQL9A52kqXnfCj8a",
34+
"acr": "LOA2",
35+
"c_hash": "lDj9nihZGSUmgNmz_lxxXA",
36+
"sub": "admin",
37+
"nbf": 1548396413,
38+
"azp": "EUVvhKM28RkwTQL9A52kqXnfCj8a",
39+
"amr": [
40+
"BasicAuthenticator",
41+
"totp"
42+
],
43+
"iss": "https://localhost:9443/oauth2/token",
44+
"exp": 1548400013,
45+
"iat": 1548396413
46+
}
47+
```
48+
49+
For SAML applications, the selected ACR value is returned in the `AuthnStatement` element of the SAML assertion:
50+
51+
```xml
52+
<saml2:AuthnStatement AuthnInstant="2019-07-03T10:26:56.645Z"
53+
SessionIndex="9e2a915b-aa69-4262-bd06-59e70c18469b">
54+
<saml2:AuthnContext>
55+
<saml2:AuthnContextClassRef>urn:federation:authentication:windows</saml2:AuthnContextClassRef>
56+
</saml2:AuthnContext>
57+
</saml2:AuthnStatement>
58+
```
59+
60+
## Translate AMR values
61+
62+
By default, the `amr` claim in the ID token contains the internal names of the authenticators used during authentication (e.g., `BasicAuthenticator`, `totp`). You can translate these to standard [RFC 8176](https://www.rfc-editor.org/rfc/rfc8176){:target="_blank"} AMR values (e.g., `pwd`, `otp`, `hwk`) by configuring {{product_name}}.
63+
64+
You can also suppress a specific authenticator from appearing in the `amr` claim entirely.
65+
66+
### Configure AMR value mappings
67+
68+
Add the following configuration to the `deployment.toml` file found in the `<IS_HOME>/repository/conf/` directory:
69+
70+
!!! note
71+
The `amr_value` should either follow the [RFC 8176 AMR specification](https://www.rfc-editor.org/rfc/rfc8176){:target="_blank"} or be any custom value you prefer to use in the `amr` claim.
72+
73+
```toml
74+
[[authentication_context.method_refs]]
75+
method = "<authenticator_name>"
76+
amr_value = "<amr_value>"
77+
```
78+
79+
The following table describes the configuration parameters:
80+
81+
| Parameter | Type | Description |
82+
|---|---|---|
83+
| `method` | String | The internal name of the authenticator as registered in {{product_name}}. |
84+
| `amr_value` | String | The AMR value to include in the ID token for the given authenticator. |
85+
| `excluded_methods` | Array of strings | Authenticators to exclude from the `amr` claim in the ID token. |
86+
87+
To prevent a specific authenticator from appearing in the `amr` claim of the ID token, use `excluded_methods`:
88+
89+
```toml
90+
[[authentication_context.method_refs]]
91+
excluded_methods = ["<authenticator_name>"]
92+
```
93+
94+
**Example:**
95+
96+
```toml
97+
[[authentication_context.method_refs]]
98+
method = "BasicAuthenticator"
99+
amr_value = "pwd"
100+
101+
[[authentication_context.method_refs]]
102+
method = "DemoFingerprintAuthenticator"
103+
amr_value = "fpt"
104+
105+
[[authentication_context.method_refs]]
106+
method = "DemoFaceIdAuthenticator"
107+
amr_value = "user"
108+
109+
[[authentication_context.method_refs]]
110+
method = "DemoHardwareKeyAuthenticator"
111+
amr_value = "hwk"
112+
113+
[[authentication_context.method_refs]]
114+
excluded_methods = ["AuthenticatorToBeHiddenFromAMR"]
115+
```
116+
117+
### Example: Translated AMR values in ID token
118+
119+
After configuring the mappings, the `amr` claim in the ID token will reflect the translated values:
120+
121+
```json
122+
{
123+
"at_hash": "6OXwfxJaTWYC56RccEhSJg",
124+
"aud": "EUVvhKM28RkwTQL9A52kqXnfCj8a",
125+
"acr": "LOA3",
126+
"c_hash": "lDj9nihZGSUmgNmz_lxxXA",
127+
"sub": "admin",
128+
"nbf": 1548396413,
129+
"azp": "EUVvhKM28RkwTQL9A52kqXnfCj8a",
130+
"amr": [
131+
"pwd",
132+
"hwk",
133+
"user"
134+
],
135+
"iss": "https://localhost:9443/oauth2/token",
136+
"exp": 1548400013,
137+
"iat": 1548396413
138+
}
139+
```
140+
141+
## Next steps
142+
143+
- [Configure ACR-based adaptive authentication]({{base_path}}/guides/authentication/conditional-auth/acr-based-adaptive-auth/)
144+
- [Conditional authentication API reference]({{base_path}}/references/conditional-auth/api-reference/)

‎en/identity-server/7.1.0/mkdocs.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -585,7 +585,9 @@ nav:
585585
- Add adaptive MFA:
586586
- Add adaptive MFA: guides/authentication/conditional-auth/adaptive-mfa.md
587587
- MFA based on user role: guides/authentication/conditional-auth/role-based-template.md
588-
- MFA based on auth context: guides/authentication/conditional-auth/acr-based-adaptive-auth.md
588+
- MFA based on auth context:
589+
- Overview: guides/authentication/conditional-auth/acr-and-amr.md
590+
- Configure ACR-based adaptive authentication: guides/authentication/conditional-auth/acr-based-adaptive-auth.md
589591
- MFA based on user store: guides/authentication/conditional-auth/user-store-based-template.md
590592
- MFA based on login-attempts: guides/authentication/conditional-auth/login-attempt-based-template.md
591593
- MFA based on user group: guides/authentication/conditional-auth/group-based-template.md

0 commit comments

Comments
 (0)