# Generic OAuth 2.0 provider

{%hackmd @codimd/docs-wide-styles %}

CodiMD can integrate any `OAuth 2.0` provider via `generic oauth 2.0 provider`.

Before setup OAuth 2.0 provider, you need to contact your OAuth 2.0 service to request some parameter described below.

1. the `authorization url` for OAuth 2.0 service
The first step of OAuth 2.0 is redirect user to OAuth 2.0 service, and the service will authenticate the user credential. If success, return `access code` to callback url (`http://<your-codimd-server.example>/auth/oauth2/callback`).

2. the `access token url` for backend to request a `access token` for OAuth 2.0 service.
The second step, CodiMD server use `access code` in step 1 to fetch `access token` for the login user.

3. `user profile api url`
After CodiMD server get `access token`, we need to known the username, email, display name. CodiMD server use `access token` with `user profile api` to get user profile data. In this step you can also specify `scope` to limit OAuth 2.0 service return what message CodiMD server can see. default scope is `email`

4. CodiMD need a `id` for identify difference user in same auth provider, you need to provide a `object path` (`user profile username attr`) to retrive username/id in user profile data

## Setting

| Environment variable name | description | required? | default value | example |
| ----------------------------------------- | --------------------------------------------- | --------- | ------------- | ----------------------------------------- |
| CMD_OAUTH2_PROVIDERNAME | OAuth 2.0 service name | true | | MyService |
| CMD_OAUTH2_BASEURL | OAuth 2.0 service url | false | | https://my-service.xyz/ |
| CMD_OAUTH2_CLIENT_ID | Client ID for OAuth 2.0 protocol | true | | atc93jf9vasdfasdf |
| CMD_OAUTH2_CLIENT_SECRET | Client Secret for OAuth 2.0 protocol | true | | asdfasdfavvtv88v@ |
| CMD_OAUTH2_SCOPE | OAuth 2.0 scope (use space to seperate) | false | email | `basic email` |
| CMD_OAUTH2_AUTHORIZATION_URL | redirect to OAuth 2.0 url | true | | https://my-service.xyz/oauth/authorize |
| CMD_OAUTH2_TOKEN_URL | backend to fetch access token api endpoint | true | | https://my-service.xyz/oauth/token |
| CMD_OAUTH2_USER_PROFILE_URL | backend to fetch user profile api endpoint | true | | https://my-service.xyz/oauth/user/profile |
| CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR | Object path to fetch username in profile data | false | username | `user.username` |
| CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR | Object path to fetch display in profile data | false | displayName | `user.displayname` |
| CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR | Object path to fetch email in profile data | false | email | `user[0].email` |

###### tags: `CodiMD` `Docs`