57f8ebfa26
* Adding check-legacy-links-format workflow * Adding test-link-rewrites workflow * chore: updates link checker workflow hash * Migrating links to new format Co-authored-by: Kendall Strautman <kendallstrautman@gmail.com>
146 lines
4 KiB
Plaintext
146 lines
4 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: ACL OIDC - HTTP API
|
|
description: The /acl/oidc endpoints are used to login via an OIDC provider.
|
|
---
|
|
|
|
# ACL OIDC HTTP API
|
|
|
|
The `/acl/oidc` endpoints are used to log in to Nomad via an OIDC provider.
|
|
|
|
## Get an OIDC authentication URL
|
|
|
|
This endpoint creates a URL which will allow the caller to navigate to their
|
|
OIDC provider and log in. The returned string is URL encoded.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ----------------------- | ------------------ |
|
|
| `POST` | `/v1/acl/oidc/auth-url` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `none` |
|
|
|
|
### Parameters
|
|
|
|
- `AuthMethodName` `(string: <required>)` - The name of the ACL authentication
|
|
method to use.
|
|
|
|
- `RedirectURI` `(string: <required>)` - The URI that the response will be sent
|
|
to when authorization is finished. The value must be included within the auth
|
|
method's allowed redirect URIs listing.
|
|
|
|
- `ClientNonce` `(string: <required>)` - A randomly generated string to prevent
|
|
replay attacks.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"AuthMethodName": "auth0",
|
|
"RedirectURI": "http://localhost:4649/oidc/callback",
|
|
"ClientNonce": "fpSPuaodKevKfDU3IeXb"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/acl/oidc/auth-url
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AuthURL": "https://some-domain.uk.auth0.com/authorize?client_id=4fOYtJiC5fo98EQj2TScs2someclient&nonce=fpSPuaodKevKfDU3IeXb&redirect_uri=http%3A%2F%2Flocalhost%3A4649%2Foidc%2Fcallback&response_type=code&scope=openid&state=st_4i68Nt7FcxDsomestate"
|
|
}
|
|
```
|
|
|
|
## Complete OIDC Authentication
|
|
|
|
This endpoint creates an ACL Role. The request is always forwarded to the
|
|
authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ---------------------------- | ------------------ |
|
|
| `POST` | `/v1/acl/oidc/complete-auth` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
[required ACLs](/nomad/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `none` |
|
|
|
|
### Parameters
|
|
|
|
- `AuthMethodName` `(string: <required>)` - The name of the ACL authentication
|
|
method to use and will match that used within the call to generate the URL.
|
|
|
|
- `RedirectURI` `(string: <required>)` - The URI that the response will be sent
|
|
to when authorization is finished. The value must be included within the auth
|
|
method's allowed redirect URIs listing.
|
|
|
|
- `ClientNonce` `(string: <required>)` - A randomly generated string to prevent
|
|
replay attacks that will match that used within the call to generate the URL.
|
|
|
|
- `State` `(string: <required>)` - An opaque value used to maintain state between
|
|
the request and the callback.
|
|
|
|
- `Code` `(string: <required>)` - The authorization code returned from the OIDC
|
|
providers authorization endpoint.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"AuthMethodName": "auth0",
|
|
"RedirectURI": "http://localhost:4649/oidc/callback",
|
|
"ClientNonce": "fpSPuaodKevKfDU3IeXb",
|
|
"State": "st_4i68Nt7FcxDsomestate",
|
|
"Code": "SplxlOBeZQQYbYS6WxSbIA"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/acl/oidc/complete-auth
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "cbbc7059-3acf-2ef5-378b-495f5f81f733",
|
|
"CreateIndex": 18,
|
|
"CreateTime": "2023-01-18T10:53:29.460987Z",
|
|
"ExpirationTTL": 600000000000,
|
|
"ExpirationTime": "2023-01-18T11:03:29.460987Z",
|
|
"Global": true,
|
|
"ModifyIndex": 18,
|
|
"Name": "OIDC-auth0",
|
|
"Policies": [],
|
|
"Roles": [
|
|
{
|
|
"ID": "10b1a678-f71d-d266-2888-8b3e47e317b8",
|
|
"Name": "engineering-read"
|
|
}
|
|
],
|
|
"SecretID": "1fce464c-06d1-4020-8564-631c25201ea7",
|
|
"Type": "client"
|
|
}
|
|
```
|