Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Client Management README #3675

Merged
merged 1 commit into from
Jan 24, 2023
Merged

Client Management README #3675

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 69 additions & 106 deletions docs/admin/auth-server/client-management/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,133 +4,96 @@ tags:
- client-management
---

# Client Management
## Background

Janssen server client management enables users to create(register), update, remove and get information about OAuth 2.0
clients(or relying parties in context of OpenId Connect).

OAuth framework defines the term `client` [here](https://datatracker.ietf.org/doc/html/rfc6749#section-1.1) and OpenId
Connect [defines relying party](https://openid.net/specs/openid-connect-core-1_0.html#Introduction) as
A "client" is a piece of software either acting autonomously or on behalf of
a person. The OAuth framework defines the term client
[here](https://datatracker.ietf.org/doc/html/rfc6749#section-1.1). OpenId Connect
[clarifies](https://openid.net/specs/openid-connect-core-1_0.html#Introduction)
that:
`OAuth 2.0 Clients using OpenID Connect are also referred to as Relying Parties (RPs)`

## Ways To Perform Client Management

### Config-API and Tools

Janssen Server [config-API](../../config-guide/config-api/README.md) module includes [API for client management](../../config-guide/config-api/openid-client.md).

Janssen Server tools like [Janssen Text-based UI(TUI)](../../config-guide/tui.md) and [jans-CLI](../../config-guide/jans-cli/README.md)
provide a way to perform client management operations. These tools use the same APIs provided by `config-API` module mentioned above.

### API For Dynamic Client Registration

Janssen Server provides client management API for dynamic client registration using
`/registration` endpoint. The OpenApi specification for
[/registration](https://gluu.org/swagger-ui/?url=https://raw.githubusercontent.com/JanssenProject/jans/vreplace-janssen-version/jans-auth-server/docs/swagger.yaml#/Registration)
endpoint contains details on how to use this endpoint to perform various client management operations along with defining
the request and response parameters. Also refer to
[documentation for /registration endpoint](../endpoints/client-registration.md) to
understand steps involved in dynamic client registration.

Below section is a step-by-step guide to for client management using [jans-CLI](../../config-guide/jans-cli/README.md) and
[Janssen Text-based UI(TUI)](../../config-guide/tui.md).

## Client Registration

In order to get token from token endpoint, a `confidential` client has to be registered with authorization server(AS),
also called OpenID Connect Provider(OP) in OpenID Connect context. Registration allow clients to specify some
vital details about itself, like [redirect_uri](./configuration/redirect-uris.md), plus information that will define
the interaction between the client and the AS/OP.

### Using Jans-CLI

TODO: add sample command

### Using TUI

To start registering a new client, navigate to `Auth Server`->`Clients`->`Add Client`. This brings up a screen as show below with various sections to input client details.

![](../../../assets/Jans_TUI_Auth_Server_Add_new_client.png)

#### Basic

| Parameter (TUI) | Request Parameter (CLI) | Description | Required | Default |
|-----------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------|
| Client_ID | | Janssen Server generates and assigns a unique identifier to a successfully registered client | No | Server Generated |
| Active | | Flag to activate or deactivate the client | No | Active |
| Client Name | | User provided name of the client | No | Blank |
| Client Secret | | User provided secret for client authentication | No | Server Generated |
| Description | | User provided description of the client | No | Blank |
| Authn Method Token Endpoint | | Method used for authenticating client at token endpoint. It can be any one of the [client authentication methods](./client-authn.md) supported by Janssen Server | No | `none` |
| Subject Type | | Type of identifier used for subject(end-user). Janssen Server supports Subject identifier [type as defined in OIDC core specification](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) | No | `public` |
| Sector Identifier URI | | User provided URI to be used in pairwise identifier algorithm [as specified in OIDC core specification](https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg) | No | Blank |
| Grant | | Enroll client for One or more [supported grant types](./configuration/grants.md) | No | `Authorization Code`, `Refresh Token` |
| Response Types | | [Response Type](./configuration/response-types.md) value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. | No | `code` |
| Suppress Authorization | | TODO | No | False |
| Application Type | | Kind of the application. The defined values are `native` or `web`. Web Clients using the OAuth Implicit Grant Type must only register URLs using the HTTPS scheme as redirect_uris; they must not use localhost as the hostname. Native Clients must only register redirect_uris using custom URI schemes or URLs using the http: scheme with localhost as the hostname. | No | `web` |
| Redirect Uris | | [Redirection URI](./configuration/redirect-uris.md) values used by the Client. One of these registered Redirection URI values must exactly match the redirect_uri parameter value used in each Authorization Request | Yes | No defaults |
| Redirect Regex | | TODO | No | Blank |
| Scopes | | List of scopes that a client can request. Refer to Janssen Server [scope documentation](../scopes/README.md) for more details | | |




#### Token

TODO: add details here
Don't confuse a client with either the Person or the Browser!
![](../../../assets/federated_identity_actors.png)

#### Logout
## Client Security

TODO: add details here
OpenID allows you to use as much security as you need. To a large extent, how
the client is configured equals how secure is your OpenID implementation. For
example, let's just consider how the client authenticates itself to Jans Auth
Server, which is defined by the `token_endpoint_auth_method` in OpenID Connect
as a [Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata) claim.

#### Software Info
| Method | Secret Not Sent in Clear | Signed | Only client has secret |
| ------ | :----------------------: | :----: | :--------------------- |
| `client_secret_basic` | | | |
| `client_secret_post` | | | |
| `client_secret_jwt` | X | X | |
| `private_key_jwt` | X | X | X |

TODO: add details here
Obviously, using asynchronous secrets for authentication is more secure. The
client configuration also determines what crypto is used for signing and
encryption of tokens, what scopes are available to the client (which determines
the extent of access to APIs), what grants are available, and what is a valid
`redirect_uri` to redirect the browser to after a front channel interaction
with Jans Auth Server. Through client configuration, you can also control other
behavior, like timeouts, interception script executions, whether to use a value
or reference token, whether to expire the client, and several other options that
impact security.

#### CIBA-PAR-UMA
## Client Tools

TODO: add details here
Jan Auth Server client management enables admins to create (register), update,
remove and get information about clients.

#### Encryption-Signing
There are a few ways clients are created and managed in Jans Auth Server:

TODO: add details here
* [Jans Config API](../../config-guide/config-api/)
* [Command Line Tool (CLI)]((../../config-guide/jans-cli/README.md))
* [Jans Text UI (TUI)](../../config-guide/tui.md)
* [OpenID Connect Dynamic Client Registration](https://openid.net/specs/openid-connect-registration-1_0.html)

#### Advanced Client Properties
Which mechanism to use depends on the deployment requirements. For *ad hoc*
creation, the TUI is great. If you need to quickly script client creation (e.g.
in a bash script), use the CLI, or use `curl` to call the Jans Config API. If
developers need to have the ability to register clients, the adopt OpenID
Connect Dynamic Client Registration.

TODO: add details here
### OpenID Dynamic Client Registration

#### Client Scripts
Jans Auth server publishes the `registration_endpoint` in the OpenID
configuration JSON response, which you can find at `.well-known/openid-configuration`
in your specific deployment. Typically, it is
`https://{hostname}/jans-auth/restv1/register`

TODO: add details here
The OpenApi specification for [/registration](https://gluu.org/swagger-ui/?url=https://raw.githubusercontent.com/JanssenProject/jans/vreplace-janssen-version/jans-auth-server/docs/swagger.yaml#/Registration) documents Jans Auth Server's specific implementation,
which aligns with the requirements of OpenID Connect dynamic client
registration. Also check the
[Registration Endpoint documentation](../endpoints/client-registration.md) for
more details on the steps involved in dynamic client registration.

## Getting Information About Existing Clients
### Jans-CLI

Use `search` to retrieve information about a particular client, while `Get Clients` will show the list of all
available clients.
Below is a one liner to add a client.

Upon selecting the client, the client details screen will shown.
```
./config-cli-tui.pyz --host $FQDN --client-id $MY_CLIENT_ID \
--client-secret $MY_CLIENT_SECRET --no-tui \
--operation-id=post-oauth-openid-client --data=my_client.json
```

![](../../../assets/Jans_TUI_Auth_Server_Client_detail.png)
For more information about how to use
the Jans-CLI, see the [docs](../../config-guide/jans-cli/README.md)

## Updating Client Configuration

- Open the client details page using steps mentioned in
[getting information](#getting-information-about-existing-clients) section.
- Update the information as required and select `save` to persist the updates.

## Deactivating A Client

Use instructions in [updating client configuration](#updating-client-configuration) to open client details
page. A client can be deactivated by unchecking the `Active` attribute.

## Interception Scripts

TODO: add more details
### Using TUI

REF:
https://docs.jans.io/v1.0.6/script-catalog/client_registration/OpenBanking/client-registration/
To start registering a new client, navigate to
`Auth Server`->`Clients`->`Add Client`. This brings up a screen as show below
with various sections to input client details.

![](../../../assets/Jans_TUI_Auth_Server_Add_new_client.png)

### Using curl

!!! Contribute
If you’d like to contribute to this document, get started with the [Contribution Guide](https://docs.jans.io/head/CONTRIBUTING/#contributing-to-the-documentation)
To add a client via `curl`, see information on the
[curl documentation page](../../config-guide/curl.md).
Binary file added docs/assets/federated_identity_actors.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.