From 067405a4fb61fba504eca4162f6b59d8718516cf Mon Sep 17 00:00:00 2001 From: pujavs <43700552+pujavs@users.noreply.github.com> Date: Wed, 30 Nov 2022 23:31:17 +0530 Subject: [PATCH] docs(config-api): updated config-api overview and configuration docs (#3129) * docs(config-api): docs for app config, plugin, attribute and client * docs(config-api): updated config-api overview and configuration docs --- docs/admin/config-api/README.md | 34 ++- .../config-api/config-api-configuration.md | 179 ---------------- docs/admin/config-api/config.md | 201 +++++++++++++++--- 3 files changed, 201 insertions(+), 213 deletions(-) delete mode 100644 docs/admin/config-api/config-api-configuration.md diff --git a/docs/admin/config-api/README.md b/docs/admin/config-api/README.md index 690d2149a60..a4083dba11d 100644 --- a/docs/admin/config-api/README.md +++ b/docs/admin/config-api/README.md @@ -4,9 +4,35 @@ tags: - config-api --- -# Overview +# config-api -Please use the left navigation menu to browse the content of this section while we are still working on developing content for `Overview` page. +## Overview +[Jans Config Api](https://github.com/JanssenProject/jans/tree/main/jans-config-api) provides a central place to manage and configure jans modules. +It helps in configuring auth-server, users, fido2 and scim modules. +Config API is a REST application that is developed using Weld 4.x (JSR-365) and JAX-RS. Its endpoints can be used to manage configuration and other properties of [Jans Auth Server] (https://github.com/JanssenProject/jans/tree/main/jans-auth-server), which is an open-source OpenID Connect Provider (OP) and UMA Authorization Server (AS) +![Config-API-Architecture](../../../assets/config-api-architecture.png) +If you want to learn more about Weld, please visit its website: https://weld.cdi-spec.org/ -!!! 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) \ No newline at end of file +## Packaging and running the application +The application can be packaged using `./mvnw package`. +It produces the `jans-config-api.war` file in the `server/target` directory. +Be aware that all the dependencies are copied into the `server/target/jans-config-api/WEB-INF/lib` directory. + +## Plugins +Jans Config API follow a flexible plugin architecture in which the new features can be added using extensions called plugins without altering the application itself. In this section, we will discuss the steps to develop and add plugins in Jans Config API. +![Refer] (/plugins.md) for more details. + +## Endpoints protection +Config API endpoints are OAuth 2.0 protected. It supports simple bearer and JWT token. + +## Documentation +Learn more in the [jans-config-api documentation](https://gluu.org/swagger-ui/?url=https://raw.githubusercontent.com/JanssenProject/jans/main/jans-config-api/docs/jans-config-api-swagger.yaml). + +### Endpoints +#### Attribute +Attributes are individual pieces of user data, like uid or email, that are required by applications in order to identify a user and grant access to protected resources. +![Refer] (./attribute.md) for more details. + +#### Default Authentication Method +Attributes are individual pieces of user data, like uid or email, that are required by applications in order to identify a user and grant access to protected resources. +![Refer] (/default-authentication-method.md) for more details. diff --git a/docs/admin/config-api/config-api-configuration.md b/docs/admin/config-api/config-api-configuration.md deleted file mode 100644 index 5647537b336..00000000000 --- a/docs/admin/config-api/config-api-configuration.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -tags: - - administration - - config-api ---- - -# Config-api-configuration - -## Overview -[Jans Config Api] (https://github.com/JanssenProject/jans/tree/main/jans-config-api) configuration enables to manage application-level configuration. -! [](https://github.com/JanssenProject/jans/raw/main/docs/assets/config-api-configuration.png) - - -### Existing Config-api dynamic configuration - -> ```javascript ->{ -> "configOauthEnabled": true, -> "apiApprovedIssuer": ["https://jans.server2"], -> "apiProtectionType": "oauth2", -> "apiClientId": "1800.0a6a17a0-0d3b-4ce5-881c-f98b2f2b75a7", -> "apiClientPassword": "BlRk0TlvJp8QJg1vs5e1vw==", -> "endpointInjectionEnabled": false, -> "authIssuerUrl": "https://jans.server2", -> "authOpenidConfigurationUrl": "https://jans.server2/.well-known/openid-configuration", -> "authOpenidIntrospectionUrl": "https://jans.server2/jans-auth/restv1/introspection", -> "authOpenidTokenUrl": "https://jans.server2/jans-auth/restv1/token", -> "authOpenidRevokeUrl": "https://jans.server2/jans-auth/restv1/revoke", -> "smallryeHealthRootPath": "/health-check", -> "disableJdkLogger":true, -> "loggingLevel":"INFO", -> "loggingLayout":"text", -> "externalLoggerConfiguration":"", -> "exclusiveAuthScopes": [ -> "jans_stat", -> "https://jans.io/scim/users.read", -> "https://jans.io/scim/users.write" -> ], -> "corsConfigurationFilters": [ -> { -> "filterName": "CorsFilter", -> "corsAllowedOrigins": "*", -> "corsAllowedMethods": "GET,PUT,POST,DELETE,PATCH,HEAD,OPTIONS", -> "corsAllowedHeaders": "", -> "corsExposedHeaders": "", -> "corsSupportCredentials": true, -> "corsLoggingEnabled": false, -> "corsPreflightMaxAge": 1800, -> "corsRequestDecorate": true, -> "corsEnabled": true -> } -> ], -> "userExclusionAttributes": [ -> "userPassword" -> ], -> "userMandatoryAttributes": [ -> "mail", -> "displayName", -> "jansStatus", -> "userPassword", -> "givenName" -> ], -> "agamaConfiguration": { -> "mandatoryAttributes": [ -> "qname", -> "source" -> ], -> "optionalAttributes": [ -> "serialVersionUID", -> "enabled" -> ] -> } ->} -> ``` - -## Revision update -`jansRevision` property of the configuration is used to manage any change -![](https://github.com/JanssenProject/jans/raw/main/docs/assets/config-api-configuration-revision) - -### Two options to make effect of the changes done to the configuration -1. Restart jans-config-api -2. Increment the `jansRevision` property of the configuration without restarting the application. The timer job will detect the change and fetch the latest configuration from the DB. - - -## Important attributes -### OAuth authorization -```configOauthEnabled``` property can be used to enable or disable the oAuth2 authorization. By default, its set to true. -> ```javascript -> ... -> "configOauthEnabled": true -> ... ->``` - -### Api protection -```apiProtectionType``` property states the protocol used for API authorization. Currently supported value is `oauth2`. -> ```javascript -> ... -> "apiProtectionType": "oauth2" -> ... ->`` - -### Api protection auth server -```apiApprovedIssuer``` property enables to set more than one authorization servers. By default, the current auth-server is set. You can add more server separated by comma. -> ```javascript -> ... -> apiApprovedIssuer": ["https://jans.server1,https://jans.server2"] -> ... ->`` - - -### Logging level -```loggingLevel``` property can be used to the change the logging level to the desired values ```(TRACE, DEBUG, INFO, WARN, ERROR)```. By default, the level is set to `INFO` -> ```javascript -> ... -> "loggingLevel":"DEBUG", -> ... ->`` - - -### Scopes other than the one defined by config-api -Config API endpoints are oAuth2 protected. These scopes are created while installation. However, there are few endpoints that require scopes defined by other modules like auth-server. -A list of these scopes is maintained in configuration in order to avoid creation of these scopes during Config API start-up. -```exclusiveAuthScopes``` property can be used to the change the logging level to the desired value ```(TRACE, DEBUG, INFO, WARN, ERROR)```. By default, the level is set to `INFO` -> ```javascript -> ... -> "exclusiveAuthScopes": [ -> "jans_stat", -> "https://jans.io/scim/users.read", -> "https://jans.io/scim/users.write" -> ], -> ... ->``` - -### User - Mandatory and exclusion attributes - -#### MandatoryAttributes: -```userMandatoryAttributes``` can be used to define mandatory attributes for User while creation and update. -> ```javascript -> ... -> "userMandatoryAttributes": [ -> "mail", -> "displayName", -> "jansStatus", -> "userPassword", -> "givenName" -> ], -> ... ->``` - -#### Exclusion attributes: -```userExclusionAttributes``` can be used to define User attributes that are not to be returned in API response. More attributes that are to be skipped in response can be added to the list. -> ```javascript -> ... -> "userExclusionAttributes": [ -> "userPassword" -> ], -> ... ->`` - - -### Agama flow configuration -```agamaConfiguration``` stores Agama related configuration used in Agama related endpoints. - -`mandatoryAttributes` list defines required attributes for Agama flow creation and update. -`optionalAttributes` list specify the optional attributes. -> ```javascript -> ... -> "agamaConfiguration": { -> "mandatoryAttributes": [ -> "qname", -> "source" -> ], -> "optionalAttributes": [ -> "serialVersionUID", -> "enabled" -> ] -> } -> ... ->``` diff --git a/docs/admin/config-api/config.md b/docs/admin/config-api/config.md index a4083dba11d..5647537b336 100644 --- a/docs/admin/config-api/config.md +++ b/docs/admin/config-api/config.md @@ -4,35 +4,176 @@ tags: - config-api --- -# config-api +# Config-api-configuration ## Overview -[Jans Config Api](https://github.com/JanssenProject/jans/tree/main/jans-config-api) provides a central place to manage and configure jans modules. -It helps in configuring auth-server, users, fido2 and scim modules. -Config API is a REST application that is developed using Weld 4.x (JSR-365) and JAX-RS. Its endpoints can be used to manage configuration and other properties of [Jans Auth Server] (https://github.com/JanssenProject/jans/tree/main/jans-auth-server), which is an open-source OpenID Connect Provider (OP) and UMA Authorization Server (AS) -![Config-API-Architecture](../../../assets/config-api-architecture.png) -If you want to learn more about Weld, please visit its website: https://weld.cdi-spec.org/ - -## Packaging and running the application -The application can be packaged using `./mvnw package`. -It produces the `jans-config-api.war` file in the `server/target` directory. -Be aware that all the dependencies are copied into the `server/target/jans-config-api/WEB-INF/lib` directory. - -## Plugins -Jans Config API follow a flexible plugin architecture in which the new features can be added using extensions called plugins without altering the application itself. In this section, we will discuss the steps to develop and add plugins in Jans Config API. -![Refer] (/plugins.md) for more details. - -## Endpoints protection -Config API endpoints are OAuth 2.0 protected. It supports simple bearer and JWT token. - -## Documentation -Learn more in the [jans-config-api documentation](https://gluu.org/swagger-ui/?url=https://raw.githubusercontent.com/JanssenProject/jans/main/jans-config-api/docs/jans-config-api-swagger.yaml). - -### Endpoints -#### Attribute -Attributes are individual pieces of user data, like uid or email, that are required by applications in order to identify a user and grant access to protected resources. -![Refer] (./attribute.md) for more details. - -#### Default Authentication Method -Attributes are individual pieces of user data, like uid or email, that are required by applications in order to identify a user and grant access to protected resources. -![Refer] (/default-authentication-method.md) for more details. +[Jans Config Api] (https://github.com/JanssenProject/jans/tree/main/jans-config-api) configuration enables to manage application-level configuration. +! [](https://github.com/JanssenProject/jans/raw/main/docs/assets/config-api-configuration.png) + + +### Existing Config-api dynamic configuration + +> ```javascript +>{ +> "configOauthEnabled": true, +> "apiApprovedIssuer": ["https://jans.server2"], +> "apiProtectionType": "oauth2", +> "apiClientId": "1800.0a6a17a0-0d3b-4ce5-881c-f98b2f2b75a7", +> "apiClientPassword": "BlRk0TlvJp8QJg1vs5e1vw==", +> "endpointInjectionEnabled": false, +> "authIssuerUrl": "https://jans.server2", +> "authOpenidConfigurationUrl": "https://jans.server2/.well-known/openid-configuration", +> "authOpenidIntrospectionUrl": "https://jans.server2/jans-auth/restv1/introspection", +> "authOpenidTokenUrl": "https://jans.server2/jans-auth/restv1/token", +> "authOpenidRevokeUrl": "https://jans.server2/jans-auth/restv1/revoke", +> "smallryeHealthRootPath": "/health-check", +> "disableJdkLogger":true, +> "loggingLevel":"INFO", +> "loggingLayout":"text", +> "externalLoggerConfiguration":"", +> "exclusiveAuthScopes": [ +> "jans_stat", +> "https://jans.io/scim/users.read", +> "https://jans.io/scim/users.write" +> ], +> "corsConfigurationFilters": [ +> { +> "filterName": "CorsFilter", +> "corsAllowedOrigins": "*", +> "corsAllowedMethods": "GET,PUT,POST,DELETE,PATCH,HEAD,OPTIONS", +> "corsAllowedHeaders": "", +> "corsExposedHeaders": "", +> "corsSupportCredentials": true, +> "corsLoggingEnabled": false, +> "corsPreflightMaxAge": 1800, +> "corsRequestDecorate": true, +> "corsEnabled": true +> } +> ], +> "userExclusionAttributes": [ +> "userPassword" +> ], +> "userMandatoryAttributes": [ +> "mail", +> "displayName", +> "jansStatus", +> "userPassword", +> "givenName" +> ], +> "agamaConfiguration": { +> "mandatoryAttributes": [ +> "qname", +> "source" +> ], +> "optionalAttributes": [ +> "serialVersionUID", +> "enabled" +> ] +> } +>} +> ``` + +## Revision update +`jansRevision` property of the configuration is used to manage any change +![](https://github.com/JanssenProject/jans/raw/main/docs/assets/config-api-configuration-revision) + +### Two options to make effect of the changes done to the configuration +1. Restart jans-config-api +2. Increment the `jansRevision` property of the configuration without restarting the application. The timer job will detect the change and fetch the latest configuration from the DB. + + +## Important attributes +### OAuth authorization +```configOauthEnabled``` property can be used to enable or disable the oAuth2 authorization. By default, its set to true. +> ```javascript +> ... +> "configOauthEnabled": true +> ... +>``` + +### Api protection +```apiProtectionType``` property states the protocol used for API authorization. Currently supported value is `oauth2`. +> ```javascript +> ... +> "apiProtectionType": "oauth2" +> ... +>`` + +### Api protection auth server +```apiApprovedIssuer``` property enables to set more than one authorization servers. By default, the current auth-server is set. You can add more server separated by comma. +> ```javascript +> ... +> apiApprovedIssuer": ["https://jans.server1,https://jans.server2"] +> ... +>`` + + +### Logging level +```loggingLevel``` property can be used to the change the logging level to the desired values ```(TRACE, DEBUG, INFO, WARN, ERROR)```. By default, the level is set to `INFO` +> ```javascript +> ... +> "loggingLevel":"DEBUG", +> ... +>`` + + +### Scopes other than the one defined by config-api +Config API endpoints are oAuth2 protected. These scopes are created while installation. However, there are few endpoints that require scopes defined by other modules like auth-server. +A list of these scopes is maintained in configuration in order to avoid creation of these scopes during Config API start-up. +```exclusiveAuthScopes``` property can be used to the change the logging level to the desired value ```(TRACE, DEBUG, INFO, WARN, ERROR)```. By default, the level is set to `INFO` +> ```javascript +> ... +> "exclusiveAuthScopes": [ +> "jans_stat", +> "https://jans.io/scim/users.read", +> "https://jans.io/scim/users.write" +> ], +> ... +>``` + +### User - Mandatory and exclusion attributes + +#### MandatoryAttributes: +```userMandatoryAttributes``` can be used to define mandatory attributes for User while creation and update. +> ```javascript +> ... +> "userMandatoryAttributes": [ +> "mail", +> "displayName", +> "jansStatus", +> "userPassword", +> "givenName" +> ], +> ... +>``` + +#### Exclusion attributes: +```userExclusionAttributes``` can be used to define User attributes that are not to be returned in API response. More attributes that are to be skipped in response can be added to the list. +> ```javascript +> ... +> "userExclusionAttributes": [ +> "userPassword" +> ], +> ... +>`` + + +### Agama flow configuration +```agamaConfiguration``` stores Agama related configuration used in Agama related endpoints. + +`mandatoryAttributes` list defines required attributes for Agama flow creation and update. +`optionalAttributes` list specify the optional attributes. +> ```javascript +> ... +> "agamaConfiguration": { +> "mandatoryAttributes": [ +> "qname", +> "source" +> ], +> "optionalAttributes": [ +> "serialVersionUID", +> "enabled" +> ] +> } +> ... +>```