Skip to content

Commit

Permalink
Conform readme to style guide
Browse files Browse the repository at this point in the history 
Signed-off-by: Jose Gonzalez <[email protected]>
  • Loading branch information
@jgomer2001
jgomer2001 authored Mar 25, 2024
1 parent 35c47aa commit 2ecd79a
Showing 1 changed file with 49 additions and 42 deletions.
91 changes: 49 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,28 @@
# Agama OpenID Connect Project

Use this project to delegate authentication to an external OAuth 2.0 or OpenID Connect provider (OP) using the *authorization code flow*.
This project can be used to delegate authentication to an external OAuth 2.0 or OpenID Connect provider (OP) using the [*authorization code flow*](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth).

## Anatomy
## Supported IDPs

The project consists of three flows that provide incremental functionality:
- Jans Auth Server

- `org.gluu.inbound.oauth2.AuthzCode`: With this flow the user's browser is redirected to the authorization page of an external OP (the specifics are passed in the input parameters). Authentication takes place there and subsequently an access token is obtained and returned to the caller of the flow
## Flows

- `org.gluu.inbound.oauth2.AuthzCodeWithUserInfo`: This flow launches `AuthzCode` and then obtains the profile data of the authenticated user by presenting an access token. Both the token and profile data are returned to the caller
|Qualified name|Description|
|-|-|
|`org.gluu.inbound.oauth2.AuthzCode`|With this flow the user's browser is redirected to the authorization page of an external OP (the specifics are passed in the input parameters). Authentication takes place there and subsequently an access token is obtained and returned to the caller of the flow|
|`org.gluu.inbound.oauth2.AuthzCodeWithUserInfo`|This flow launches `AuthzCode` and then obtains the profile data of the authenticated user by presenting an access token. Both the token and profile data are returned to the caller|
|`org.gluu.inbound.openid`|This flow displays an identity provider selection page and launches `AuthzCodeWithUserInfo`. Once the browser returns back from the external site, an entry in the local Jans database for the user in question is inserted. The list of supported providers and their associated settings are supplied through the project configuration. This is data supplied post-deployment|

- `org.gluu.inbound.openid`: This flow displays an identity provider selection page and launches `AuthzCodeWithUserInfo`. Once the browser returns back from the external site, an entry in the local Jans database for the user in question is inserted. The list of supported providers and their associated settings are supplied through the project configuration. This is data supplied post-deployment

## Configuration properties
## Configuration

This project must be configured using a JSON document that follows the structure below:

```
{
"org.gluu.inbound.openid": {
"OP1_ID": { configs for identity provider 1 },
"OP2_ID": { configs for identity provider 2 },
"OP1_ID": { ... configs for identity provider 1 ... },
"OP2_ID": { ... configs for identity provider 2 ... },
...
}
}
Expand All @@ -31,15 +33,42 @@ The configuration for a given OP is as follows:
|Name|Description|Notes|
|-|-|-|
|`host`|Location of the identity provider, eg. `https://my.idp.co`|Required if DCR is enabled|
|`dcr`|A JSON object configuring _Dynamic Client Registration_ (DCR) - see [below](#dcr-settings)|Optional|
|`oauth`|A JSON object following the structure referenced [here](#authzcodewithuserinfo-and-authzcode)||
|`oauth`|A JSON object following the structure referenced [here](#oauth-settings)||
|`dcr`|A JSON object configuring _Dynamic Client Registration_ - [DCR](#dcr-settings)|Optional|
|`acrValues`|A string supplying _Authentication Context Class Reference_ values|Optional|
|`provision`|A JSON object configuring how the user is [provisioned](#user-provisioning)|Required|

Regarding the `oauth` section, **not all fields** marked as required are necessary when DCR is used. It suffices to supply `scopes`.

### Example

## oauth settings

|Name|Description|Notes|
|-|-|-|
|`authzEndpoint`|The authorization endpoint as in section 3.1 of [RFC 7649](https://www.ietf.org/rfc/rfc6749)|Required|
|`tokenEndpoint`|The token endpoint as in section 3.2 of [RFC 7649](https://www.ietf.org/rfc/rfc6749)|Required|
|`userInfoEndpoint`|The endpoint where profile data can be retrieved. This is not part of the OAuth2 specification|Optional|
|`clientId`|The identifier of the client to use, see section 1.1 and 2.2 of [RFC7649](https://www.ietf.org/rfc/rfc6749). This client is assumed to be *confidential* as in section 2.1|Required|
|`clientSecret`|Secret associated to the client|Required|
|`scopes`|An array of strings that represent the scopes of the access tokens to retrieve|Required|
|`redirectUri`|Redirect URI as in section 3.1.2 of [RFC 7649](https://www.ietf.org/rfc/rfc6749)|Optional (auto filled when missing)|
|`clientCredsInRequestBody`|`true` indicates the client authenticates at the token endpoint by including the credentials in the body of the request, otherwise, HTTP Basic authentication is assumed. See section 2.3.1 of [RFC 7649](https://www.ietf.org/rfc/rfc6749)|Optional. `false` is assumed if not supplied|
|`custParamsAuthReq`|An Agama map (keys and values expected to be strings) with extra parameters to pass to the authorization endpoint if desired|Optional|
|`custParamsTokenReq`|An Agama map (keys and values expected to be strings) with extra parameters to pass to the token endpoint if desired|Optional|

### DCR settings

The structure of `dcr` is as follows:

|Name|Description|Notes|
|-|-|-|
|`enabled`|A boolean value indicating if DCR will be used for the external OP|Required<!--Optional. `false` value assumed if missing-->|
|`useCachedClient`|Once the first client registration takes place, no more registration attempts will be made until the client is about to expire. Set this to `false` to force registration every time `openid` flow is launched|Required|

### User provisioning

This process is driven by two string properties: `uidPrefix` and `attribute`. The user inserted in the local DB will have an `uid` equal to the concatenation of `uidPrefix` and the profile `attribute` as released by the external identity provider.

### Sample JSON

Here is an example that configures an OP with DCR and an OAuth 2.0 provider:

Expand Down Expand Up @@ -79,35 +108,9 @@ Here is an example that configures an OP with DCR and an OAuth 2.0 provider:
```

### DCR settings

The structure of `dcr` is as follows:

|Name|Description|Notes|
|-|-|-|
|`enabled`|A boolean value indicating if DCR will be used for the external OP|Required<!--Optional. `false` value assumed if missing-->|
|`useCachedClient`|Once the first client registration takes place, no more registration attempts will be made until the client is about to expire. Set this to `false` to force registration every time `openid` flow is launched|Required|

### User provisioning

This process is driven by two string properties: `uidPrefix` and `attribute`. The user inserted in the local DB will have an `uid` equal to the concatenation of `uidPrefix` and the profile `attribute` as released by the external identity provider.

## `AuthzCodeWithUserInfo` and `AuthzCode`

Each of these flows receive an input parameter (`oauthParams`) to drive their behavior. `oauthParams` adheres to the following structure:
## Demo

|Name|Description|Notes|
|-|-|-|
|`authzEndpoint`|The authorization endpoint as in section 3.1 of [RFC 7649](https://www.ietf.org/rfc/rfc6749)|Required|
|`tokenEndpoint`|The token endpoint as in section 3.2 of [RFC 7649](https://www.ietf.org/rfc/rfc6749)|Required|
|`userInfoEndpoint`|The endpoint where profile data can be retrieved. This is not part of the OAuth2 specification|Optional|
|`clientId`|The identifier of the client to use, see section 1.1 and 2.2 of [RFC7649](https://www.ietf.org/rfc/rfc6749). This client is assumed to be *confidential* as in section 2.1|Required|
|`clientSecret`|Secret associated to the client|Required|
|`scopes`|An array of strings that represent the scopes of the access tokens to retrieve|Required|
|`redirectUri`|Redirect URI as in section 3.1.2 of [RFC 7649](https://www.ietf.org/rfc/rfc6749)|Optional (auto filled when missing)|
|`clientCredsInRequestBody`|`true` indicates the client authenticates at the token endpoint by including the credentials in the body of the request, otherwise, HTTP Basic authentication is assumed. See section 2.3.1 of [RFC 7649](https://www.ietf.org/rfc/rfc6749)|Optional. `false` is assumed if not supplied|
|`custParamsAuthReq`|An Agama map (keys and values expected to be strings) with extra parameters to pass to the authorization endpoint if desired|Optional|
|`custParamsTokenReq`|An Agama map (keys and values expected to be strings) with extra parameters to pass to the token endpoint if desired|Optional|
Check out this [video](https://www.loom.com/share/c388a650f900455fb586649b155df6a8?sid=01abc7ec-1bb7-45da-adc7-3fecebd68c04)

## FAQ

Expand All @@ -119,3 +122,7 @@ Supply the following: `https://<jans-server-host-name>/jans-auth/fl/callback`
### What methods for token endpoint authentication are supported?

Only `client_secret_basic` and `client_secret_post` are supported

## License

This project is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license.

0 comments on commit 2ecd79a

Please sign in to comment.