> For the complete documentation index, see [llms.txt](https://icij.gitbook.io/datashare/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://icij.gitbook.io/datashare/server-mode/user-management/oauth2.md).

# OAuth2

OAuth2 authentication is selected with `--auth oauth`. With OAuth2 you delegate authentication to an external identity provider (IdP) such as KeyCloak, Okta, or GitHub. Datashare redirects unauthenticated users to the IdP, receives an authorization code, exchanges it for a token, then fetches the user profile.

<figure><img src="https://i.imgur.com/uHVXObS.png" alt="A diagram of a workflow"><figcaption><p>oauth</p></figcaption></figure>

## Configuration options

| Option                         | Required  | Description                                                                                                                        |
| ------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--oauthClientId`              | Yes       | OAuth2 client id registered with the IdP.                                                                                          |
| `--oauthClientSecret`          | Yes       | OAuth2 client secret. Also used as the default session signing key if `--sessionSigningKey` isn't set.                             |
| `--oauthAuthorizeUrl`          | Yes       | IdP endpoint that shows the login page and issues the authorization code.                                                          |
| `--oauthTokenUrl`              | Yes       | IdP endpoint that exchanges the code for an access token.                                                                          |
| `--oauthApiUrl`                | Yes       | IdP endpoint that returns the authenticated user profile as JSON.                                                                  |
| `--oauthCallbackPath`          | Yes       | Path inside Datashare that the IdP redirects back to (e.g. `/auth/callback`). Must match the redirect URI registered with the IdP. |
| `--oauthScope`                 | Sometimes | OAuth2 scopes to request. Required for OIDC providers (typically `openid email profile`).                                          |
| `--oauthClaimIdAttribute`      | No        | Name of the field in the user JSON that contains the user id. Defaults to the IdP's standard.                                      |
| `--oauthUserProjectsAttribute` | No        | Name of the field in the user JSON that contains the list of projects the user can access.                                         |
| `--oauthDefaultProject`        | No        | Project assigned to OAuth2 users when no project list is returned.                                                                 |

## Expected user profile

`--oauthApiUrl` must return a JSON object identifying the user. At a minimum, it must contain the id attribute selected by `--oauthClaimIdAttribute` (or the IdP default). To grant project access from the IdP rather than from Datashare, include the field named by `--oauthUserProjectsAttribute` as a JSON array of index names. Otherwise users are assigned to `--oauthDefaultProject`.

## Example

```
docker run -ti ICIJ/datashare:version --mode SERVER \
    --auth oauth \
    --oauthClientId 30045255030c6740ce4c95c \
    --oauthClientSecret 10af3d46399a8143179271e6b726aaf63f20604092106 \
    --oauthAuthorizeUrl https://my.oauth-server.org/oauth/authorize \
    --oauthTokenUrl https://my.oauth-server.org/oauth/token \
    --oauthApiUrl https://my.oauth-server.org/api/v1/me.json \
    --oauthCallbackPath /auth/callback
```

## Integration with KeyCloak

A small demo [repository](https://github.com/ICIJ/datashare-keycloak-integration) shows how to wire Datashare to a KeyCloak instance end-to-end.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://icij.gitbook.io/datashare/server-mode/user-management/oauth2.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.