You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Access tokens provide limited authorization to resources within a resource server. The resource server is responsible for validating these tokens before granting access. Token validation differs based on the [type of the access tokens]({{base_path}}/references/app-settings/oidc-settings-for-app/#access-token) that the resource server receives.
3
+
While resource servers can validate JSON Web Tokens (JWT) locally, opaque access tokens don't carry authorization information that a resource server can decode. The resource server must validate the token by querying the authorization server.
4
4
5
-
## Validate JWT tokens
5
+
{{product_name}} supports token validation through the **OAuth 2.0 Token Introspection endpoint** defined in [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662){: target="_blank"}.
6
6
7
-
A JSON Web Token (JWT) is a self-contained token. This means that the resource server does not need to interact with the identity provider to validate tokens. The payload of a sample decoded JWT token is as shown below.
7
+
`https://<IS_HOST>:<IS_PORT>/oauth2/introspect`
8
8
9
-
```json
10
-
{
11
-
"sub": "Alica@bifrost.com",
12
-
"aut": "APPLICATION_USER",
13
-
"aud": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
14
-
"nbf": 1623904805,
15
-
"azp": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
16
-
"scope": "openid",
17
-
"iss": "{{product_url_sample}}/oauth2/token",
18
-
"exp": 1623908405,
19
-
"iat": 1623904805,
20
-
"jti": "9fac7747-bb2d-46be-bef2-a95b2f69f8b2"
21
-
}
22
-
```
9
+
The resource server sends the access token to this endpoint, and the authorization server responds with metadata about the token, such as its validity, scopes, and expiry time.
23
10
24
-
## Validate opaque tokens
11
+
## Prerequisites
25
12
26
-
Unlike JWT tokens, opaque tokens are non-transparent. This means that the authorization information is not readily available to resource servers and they should interact with the identity provider to validate and extract the relevant information. OAuth2.0 supports [token introspection](https://datatracker.ietf.org/doc/html/rfc7662){:target="_blank"} to inspect access tokens and refresh tokens.
13
+
By default, to invoke the introspection endpoint, the caller must have the `internal_oauth2_introspect` scope.
27
14
28
-
{{ product_name }} provides the following endpoint to perform token validation.
15
+
- To customize the scopes callers must present, add the following to `<IS_HOME>/repository/conf/deployment.toml`.
29
16
30
-
```
31
-
{{product_url_format}}/oauth2/introspect
32
-
```
17
+
```toml
18
+
[resource_access_control.introspect]
19
+
scopes = ["internal_oauth2_introspect"]
20
+
```
33
21
34
-
{% if product_name == 'Asgardeo' %}
35
-
=== "Request format"
22
+
- To **remove all scope requirements** and allow any authenticated caller to introspect tokens, set `scopes` to an empty list.
36
23
37
-
```bash
38
-
curl --location --request POST {{product_url_format}}/oauth2/introspect \
!!! warning "Avoid using high-privileged credentials"
59
+
Don't use super administrator or highly privileged user credentials when invoking the introspection endpoint.
60
+
Instead, create a user with the least privileges required to call the API.
76
61
77
-
!!! warning "Avoid using super admin credentials for API authentication"
62
+
### With client credentials
78
63
79
-
When invoking APIs using basic authentication, never use the super admin or any high-privileged user credentials. Instead, create a user with the least privileges required to invoke the API and use that user's credentials.
64
+
By default, {{product_name}} only supports basic authentication with user credentials. You can enable client authentication and allow applications to call the introspection endpoint using their client ID and client secret.
80
65
81
-
{% if product_name == "WSO2 Identity Server" %}
66
+
1. To enable authentication with client credentials, add the following configuration to `<IS_HOME>/repository/conf/deployment.toml`.
82
67
83
-
!!! note
84
-
Enable the following in `<IS_HOME>/repository/conf/deployment.toml` to use client ID- client secret based authentication for this endpoint.
85
-
By default, the endpoint uses username-password authentication.
86
-
87
-
``` toml
68
+
```toml
88
69
[[resource.access_control]]
89
70
context="(.*)/oauth2/introspect(.*)"
90
-
http_method = "all"
91
-
secure = true
71
+
http_method="all"
72
+
secure=true
92
73
allowed_auth_handlers="BasicClientAuthentication"
93
74
```
94
75
76
+
2. Invoke the endpoint using the client ID and client secret.
77
+
78
+
!!! info
79
+
80
+
Ensure that the application can request this scope. Learn more about [authorizing applications to consume API resources]({{base_path}}/guides/authorization/api-authorization/api-authorization/#authorize-apps-to-consume-api-resources/).
81
+
95
82
=== "Request format"
96
83
97
84
```bash
98
-
curl --location --request POST {{product_url_format}}/oauth2/introspect \
85
+
curl --location --request POST https://localhost:9443/oauth2/introspect \
The authorization server responds to the introspection request with a JSON object containing metadata about the token. The responses change slightly based on the token type.
117
103
118
-
User access tokens are tokens generated through user interactions, such as logging in by entering credentials. The access token represents the user and the user's permissions.
104
+
### User tokens
119
105
120
-
The following response will be returned for the provided user access token:
106
+
WSO2 Identity Server issues user access tokens during user interactions, such as when users sign in. An access token represents the user and their permissions.
121
107
122
-
```json
123
-
{
124
-
"aut": "APPLICATION_USER",
125
-
"nbf": 1629961093,
126
-
"scope": "openid profile",
127
-
"active": true,
128
-
"token_type": "Bearer",
129
-
"exp": 1629968693,
130
-
"iat": 1629961093,
131
-
"client_id": "Wsoq8t4nHW80gSnPfyDvRbiC__Eb",
132
-
"username": "{{ username }}"
133
-
}
134
-
```
108
+
For a provided user token, the response looks like the following:
135
109
136
-
The following response will be returned for the provided refresh token:
110
+
=== "Access token"
137
111
138
-
```json
139
-
{
140
-
"nbf": 1629961093,
141
-
"scope": "openid profile",
142
-
"active": true,
143
-
"token_type": "Refresh",
144
-
"exp": 1630047493,
145
-
"iat": 1629961093,
146
-
"client_id": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
147
-
"username": "{{ username }}"
148
-
}
149
-
```
112
+
```json
113
+
{
114
+
"aut": "APPLICATION_USER",
115
+
"nbf": 1629961093,
116
+
"scope": "openid profile",
117
+
"active": true,
118
+
"token_type": "Bearer",
119
+
"exp": 1629968693,
120
+
"iat": 1629961093,
121
+
"client_id": "Wsoq8t4nHW80gSnPfyDvRbiC__Eb",
122
+
"username": "admin@carbon.super"
123
+
}
124
+
```
150
125
151
-
If the token you used is invalid, you will get the following response:
126
+
=== "Refresh token"
127
+
128
+
```json
129
+
{
130
+
"nbf": 1629961093,
131
+
"scope": "openid profile",
132
+
"active": true,
133
+
"token_type": "Refresh",
134
+
"exp": 1630047493,
135
+
"iat": 1629961093,
136
+
"client_id": "Wsoq8t4nHW80gSnPfyDvRbiC__Ea",
137
+
"username": "admin@carbon.super"
138
+
}
139
+
```
152
140
153
-
```json
154
-
{'active':false}
155
-
```
141
+
=== "Invalid token"
156
142
157
-
!!! note
158
-
See the [OAuth2.0 introspection request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1){:target="_blank"} for details.
143
+
```json
144
+
{"active":false}
145
+
```
159
146
160
-
### Application access token response
147
+
### Application tokens
161
148
162
-
Application access tokens are tokens obtained through grant types like the [client_credentials]({{base_path}}/references/grant-types/#client-credentials-grant) grant, without any user involvement. Unlike user-bound tokens, application access tokens represent the application itself rather than an individual user.
149
+
Applications receive application tokens through grant types like the clientcredentials grant, which don't involve any user interaction. These tokens represent the application itself rather than an individual user.
163
150
164
-
The introspection response for Application access Ttkens follows the format shown below:
151
+
For a provided application token, the response looks like the following:
165
152
166
153
```json
167
154
{
@@ -177,8 +164,8 @@ The introspection response for Application access Ttkens follows the format show
177
164
178
165
!!! warning "Deprecated behavior"
179
166
180
-
Previously, the introspection response for application access tokens included the `username` attribute, which contained the application owner's username. This attribute will no longer be included in the introspection response.
181
-
182
-
If your application's access tokens still return the response, it is likely that your application is out-of-date. If so, update your application through the {{product_name}} Console by navigating to the relevant application under the **Applications** section.
167
+
Previously, the introspection response for application access tokens included the `username` attribute, which contained the username of the application owner. This attribute will no longer be included in the introspection response.
168
+
169
+
If your application's access tokens still return the response, it is likely that your application is out-of-date. If so, update your application through the WSO2 Identity Server Console by navigating to the relevant application under the Applications section.
183
170
184
-
Once updated, the `username` attribute will no longer be included in the introspection response. Therefore, before updating, ensure that your application does not rely on the `username` attribute and remove any such dependencies.
171
+
Once updated, the username attribute will no longer be included in the introspection response. Therefore, before updating, ensure that your application does not rely on the username attribute and remove any such dependencies.
0 commit comments