Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc(jans-auth-server): AS supports OAuth 2.0 Token Exchange but there is no docs for it #7352 #8176

Merged
merged 2 commits into from
Mar 29, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/admin/auth-server/endpoints/token.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,14 +119,20 @@ navigate via `Auth Server`->`Clients`->`Add Client`->`Basic`-> `Authn Method Tok

![](../../../assets/image-tui-client-registration-basic.png)


## Supported Grant Types

Token endpoint supports below mentioned grant types.

- [Authorization Code](../oauth-features/auth-code-grant.md)
- [Implicit](../oauth-features/implicit-grant.md)
- [Refresh Token](../oauth-features/README.md)
- [Client Credentials](../oauth-features/client-credential-grant.md)
- [Password](../oauth-features/password-grant.md)
- [Token Exchange](../oauth-features/token-exchange.md)
- [Transaction Tokens](../tokens/oauth-tx-tokens.md)
- [Device Grant](../oauth-features/device-grant.md)
- [CIBA](./backchannel-authentication.md)

Client can configure all the possible grant types it can request from token endpoint during client configuration.
To select the available grant types using
Expand Down
66 changes: 66 additions & 0 deletions docs/admin/auth-server/oauth-features/token-exchange.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
tags:
- administration
- auth-server
- oauth
- token
- toke-exchange
---

# OAuth 2.0 Token Exchange (RFC 8693)

Token Exchange is an extension to OAuth 2.0 for implementing use cases when one token needs to be exchanged for another token.
The exchange occurs at the Token Endpoint of an authorization server, with a special `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`.

The client makes a token exchange request to the Token Endpoint with an extension grant type using the HTTP POST method.
HTTP request entity-body should be `application/x-www-form-urlencoded` with a character encoding of UTF-8.

`subject_token_type` parameter must have `urn:ietf:params:oauth:token-type:id_token` value. It means that
`subject_token` must be valid `id_token` issued by this AS.

"Token Exchange" interception script allows to customize logic including
`subject_token_type`, `subject_token` parameters validation and response of token exchange.

**Sample request**

```curl
POST /as/token.oauth2 HTTP/1.1
Host: as.example.com
Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=https%3A%2F%2Fbackend.example.com%2Fapi
&subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token
```

**Sample response**
```curl
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
"access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo
dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV
4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn
N1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQedw6rx
f59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIWvmDCM
y5-kdXjwhw",
"issued_token_type":
"urn:ietf:params:oauth:token-type:access_token",
"token_type":"Bearer",
"expires_in":60
}
```

AS supports following token types in response:

- urn:ietf:params:oauth:token-type:access_token
- urn:ietf:params:oauth:token-type:refresh_token
- urn:ietf:params:oauth:token-type:id_token

## References

- [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693)