[release-12.3.0] Restructure As code and developer resources (#113969)
Co-authored-by: Roberto Jiménez Sánchez <roberto.jimenez@grafana.com> Co-authored-by: Anna Urbiztondo <anna.urbiztondo@grafana.com>
This commit is contained in:
Jack Baldry
GitHub
@@ -0,0 +1,251 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/sso-settings/ # /docs/grafana/next/http_api/sso-settings/
|
||||
- ../../../http_api/ssosettings/ # /docs/grafana/next/http_api/ssosettings/
|
||||
- ../../../developers/http_api/sso-settings/ # /docs/grafana/next/developers/http_api/sso-settings/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/sso-settings/
|
||||
description: Grafana SSO Settings API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- sso
|
||||
- sso-settings
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: SSO Settings API
|
||||
---
|
||||
|
||||
# SSO Settings API
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
The API can be used to create, update, delete, get, and list SSO Settings for OAuth2 and SAML.
|
||||
|
||||
The settings managed by this API are stored in the database and override
|
||||
[settings from other sources](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/)
|
||||
(arguments, environment variables, settings file, etc).
|
||||
Therefore, every time settings for a specific provider are removed or reset to the default settings at runtime,
|
||||
the settings are inherited from the other sources in the reverse order of precedence
|
||||
(`arguments > environment variables > settings file`).
|
||||
|
||||
## List SSO Settings
|
||||
|
||||
`GET /api/v1/sso-settings`
|
||||
|
||||
Lists the SSO Settings for all providers.
|
||||
|
||||
The providers or SSO keys that are not managed by this API are retrieved from the other sources (settings file, environment variables, default values).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ---------------------------- |
|
||||
| `settings:read` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/v1/sso-settings HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – SSO Settings found
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
|
||||
## Get SSO Settings
|
||||
|
||||
`GET /api/v1/sso-settings/:provider`
|
||||
|
||||
Gets the SSO Settings for a provider.
|
||||
|
||||
The SSO keys that are not managed by this API are retrieved from the other sources (settings file, environment variables, default values).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ---------------------------- |
|
||||
| `settings:read` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/v1/sso-settings/github HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
ETag: db87f729761898ee
|
||||
{
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – SSO Settings found
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – SSO Settings not found
|
||||
|
||||
## Update SSO Settings
|
||||
|
||||
`PUT /api/v1/sso-settings/:provider`
|
||||
|
||||
Updates the SSO Settings for a provider.
|
||||
|
||||
When you submit new settings for a provider via API,
|
||||
Grafana verifies whether the given settings are allowed and valid.
|
||||
If they are, then Grafana stores the settings in the database and reloads
|
||||
Grafana services with no need to restart the instance.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
If you run Grafana in high availability mode, configuration changes
|
||||
may not get applied to all Grafana instances immediately. You may need
|
||||
to wait a few minutes for the configuration to propagate to all Grafana instances.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `settings:write` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/v1/sso-settings/github HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **204** – SSO Settings updated
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
|
||||
## Delete SSO Settings
|
||||
|
||||
`DELETE /api/v1/sso-settings/:provider`
|
||||
|
||||
Deletes an existing SSO Settings entry for a provider.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `settings:write` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/v1/sso-settings/azuread HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **204** – SSO Settings deleted
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – SSO Settings not found
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **204** – SSO Settings updated
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
|
||||
## Delete SSO Settings
|
||||
|
||||
`DELETE /api/v1/sso-settings/:provider`
|
||||
|
||||
Deletes an existing SSO Settings entry for a provider.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `settings:write` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/v1/sso-settings/azuread HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **204** – SSO Settings deleted
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – SSO Settings not found
|
||||
Reference in New Issue
Block a user