From 5ce21aac5df54d2fe9402479fd221fffe9dc77ef Mon Sep 17 00:00:00 2001 From: Madhumita Subramaniam Date: Tue, 1 Nov 2022 19:56:48 +0530 Subject: [PATCH] fix: #2825 (#2828) --- .../endpoints/client-registration.md | 50 +++++++++---------- .../customization/customize-web-pages.md | 14 +++--- docs/admin/developer/interception-scripts.md | 2 +- .../scripts/person-authentication.md | 42 ++++++++-------- 4 files changed, 54 insertions(+), 54 deletions(-) diff --git a/docs/admin/auth-server/endpoints/client-registration.md b/docs/admin/auth-server/endpoints/client-registration.md index 4be04838a62..689b108ccf4 100644 --- a/docs/admin/auth-server/endpoints/client-registration.md +++ b/docs/admin/auth-server/endpoints/client-registration.md @@ -12,9 +12,9 @@ tags: Dynamic client registration refers to the process by which a client submits a registration request to the Authorization server and how that request is served by the Authorization server. It is explained in the following specifications: -1. For OpenID Connect relying parties - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html). +1. For OpenID Connect relying parties - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html). 1. For OAuth 2.0 client (without OpenID Connect features) - [OAuth 2.0 Dynamic Client Registration Protocol - RFC 7591](https://tools.ietf.org/html/rfc7591). -1. CRUD operations on client - [OAuth 2.0 Dynamic Client Registration Management Protocol - RFC 7592](https://tools.ietf.org/html/rfc7592). +1. CRUD operations on client - [OAuth 2.0 Dynamic Client Registration Management Protocol - RFC 7592](https://tools.ietf.org/html/rfc7592). ### Client Registration endpoint The URI to dynamically register a client to a Janssen Auth Server can be found by checking the `registration_endpoint` claim of the OpenID Connect configuration reponse, typically deployed at `https:///.well-known/openid-configuration` @@ -32,17 +32,17 @@ Configure the Janssen AS using steps explained in the [link](#curl-commands-to-c #### 1. A simple client registration request (with mandatory parameter): ``` curl -X POST -k -i 'https://my.jans.server/jans-auth/restv1/register' \ - --data '{ \ + --data '{ \ "redirect_uris": ["https://client.example.org/cb"] \ }' \ ``` -#### 2. A typical client registration request : +#### 2. A typical client registration request : A typical client registration request : A client or developer calls the client registration endpoint with a set of client metadata as specified in [RFC7591](https://www.rfc-editor.org/rfc/rfc7591.html#page-8) ``` curl -X POST -k -i 'https://my.jans.server/jans-auth/restv1/register' \ - --data '{ \ + --data '{ \ "redirect_uris": ["https://client.example.org/cb"] \ "client_id": "c3BhdRkqfX", \ "client_secret": "bd136123eeffeef234235805d", \ @@ -54,13 +54,13 @@ A typical client registration request : A client or developer calls the client r }' \ ``` #### 3. Client Registration Request Using a signed request object -In some usecases like FAPI implementation, DCR request payload is a JWT. +In some usecases like FAPI implementation, DCR request payload is a JWT. Example: ``` curl -X POST -k -H 'Content-Type: application/jwt' \ -H 'Accept: application/json' \ -i 'https://my-jans-server/jans-auth/restv1/register' \ - --data 'eyJraWQiOiJrWTIyZXBUT......ueOg2HkjpggwAEP84jq9Q' + --data 'eyJraWQiOiJrWTIyZXBUT......ueOg2HkjpggwAEP84jq9Q' ``` When such will be the nature of client registration requests, the following configuration properties should be set in the authorization server: - `dcrSignatureValidationEnabled` - enables DCR signature validation @@ -68,9 +68,9 @@ When such will be the nature of client registration requests, the following conf - `dcrSignatureValidationJwks` - specifies JWKS for all DCR's validations. Configure the Janssen AS using steps explained in the [link](#curl-commands-to-configure-jans-auth-server) -#### 4. Client registration using software statement +#### 4. Client registration using software statement A signed assertion from a trusted party, a Software statement or Software Statement Assertion (SSA), is used to dynamically register clients to an Authorization server. -Example: +Example: ``` #!/bin/bash curl -X POST https://my.jans.server/jans-auth/restv1/register \ -H "Content-Type: application/json" \ @@ -81,7 +81,7 @@ Example: } DATA ``` For Client registrations using Software statements, the AS should be configured using the following configuration parameters: - - `softwareStatementValidationType` - The value of this variable is one of the following: + - `softwareStatementValidationType` - The value of this variable is one of the following: - NONE - validation is skipped for software statement - SCRIPT - (default), invokes `getSoftwareStatementJwks` of dynamic registration script which has to return jwks. - JWKS - claim name within software statement that has inlined JWKS @@ -90,15 +90,10 @@ For Client registrations using Software statements, the AS should be configured - `dcrSignatureValidationSoftwareStatementJwksClaim` - specifies claim name inside software statement. Value of claim should point to inlined JWKS. Configure the AS using steps explained in the [link](#curl-commands-to-configure-jans-auth-server) - + #### 5. Special mention about FAPI: In case of a typical [client registration request in FAPI implementation]( https://openbankinguk.github.io/dcr-docs-pub/v3.3/dynamic-client-registration.html), the request object which is a signed JWT (as seen in point 3) is also called an SSA (Software statement Assertion) or DCR payload. This SSA can contain the software_statement inside it which is also a signed JWT. Each of the JWTs, the outer JWT called the SSA and the inner JWT called the software_statement are signed by different entities - the TPP and OBIE respectively. - - -### Customizing the behavior of OP during DCR using an interception script: -The Janssen Authorization Server uses [`ClientRegistrationType`](https://github.com/JanssenProject/jans/blob/main/jans-core/script/src/main/java/io/jans/model/custom/script/type/client/ClientRegistrationType.java) interception scripts to enable you to customize the behavior of the OpenID Provider during client registration. Examples of business customizations in the client registration script are validating certificates against a certificate directory, manage client claims, modify scopes, perform validation and checks. -Reference : ### Security Pointers If `dynamicRegistrationEnabled` is enabled in the Authorization Server, assess the following points to minimize potential exposure of sensitive personal data: @@ -107,18 +102,18 @@ If `dynamicRegistrationEnabled` is enabled in the Authorization Server, assess t 2. `dynamicRegistrationScopesParamEnabled` controls whether default scopes are globally enabled. If `dynamicRegistrationScopesParamEnabled` is `true` then scopes defined as default will be automatically added to any dynamically registered client entry without consent of OP's administrator. Therefore, make an informed decision before setting this field to `true`. -### CURL commands to configure Jans-auth server +### CURL commands to configure Jans-auth server Jans-auth server is configured using [Jans Config Api](https://github.com/JanssenProject/jans/tree/main/jans-config-api) : -1. Obtain the access token +1. Obtain the access token ``` curl -u "put_client_id_here:put_config_api_client_secret_here" https:///jans-auth/restv1/token \ -d "grant_type=client_credentials&scope=https://jans.io/oauth/jans-auth-server/config/properties.write" ``` 2. Patch jans-auth server configurations to reflect `anExampleConfigField` with the value `anExampleConfigField_value` - + ``` - curl -X PATCH -k -H 'Content-Type: application/json-patch+json' \ - -i 'https:///jans-config-api/api/v1/jans-auth-server/config' \ + curl -X PATCH -k -H 'Content-Type: application/json-patch+json' \ + -i 'https:///jans-config-api/api/v1/jans-auth-server/config' \ -H "Authorization: Bearer put_access_token_here" --data '[ { "op": "add", @@ -130,8 +125,8 @@ Jans-auth server is configured using [Jans Config Api](https://github.com/Jansse Example : Patch jans-auth server configurations to reflect `dynamicRegistrationEnabled` with value as `true` ``` - curl -X PATCH -k -H 'Content-Type: application/json-patch+json' \ - -i 'https:///jans-config-api/api/v1/jans-auth-server/config' \ + curl -X PATCH -k -H 'Content-Type: application/json-patch+json' \ + -i 'https:///jans-config-api/api/v1/jans-auth-server/config' \ -H "Authorization: Bearer put_access_token_here" --data '[ { "op": "add", @@ -301,11 +296,14 @@ Output: "description": "string" } ``` -### Dynamic registration custom attributes +### Customizing the behavior of the AS using Interception script +Janssen's allows developers to register a client with the Authorization Server (AS) without any intervention by the administrator. By default, all clients are given the same default scopes and attributes. Through the use of an interception script, this behavior can be modified. These scripts can be used to analyze the registration request and apply customizations to the registered client. For example, a client can be given specific scopes by analyzing the [Software Statement](https://www.rfc-editor.org/rfc/rfc7591.html#section-2.3) that is sent with the registration request. +Further reading [here](../../developer/scripts/client-registration.md) -### CRUD Operations +### Dynamic registration custom attributes -### Internationalization for Client metadata +### CRUD Operations +### Internationalization for Client metadata diff --git a/docs/admin/developer/customization/customize-web-pages.md b/docs/admin/developer/customization/customize-web-pages.md index c65691dc324..b0061efde1f 100644 --- a/docs/admin/developer/customization/customize-web-pages.md +++ b/docs/admin/developer/customization/customize-web-pages.md @@ -5,9 +5,9 @@ tags: - customization --- -All web pages are **xhtml** files. +All web pages are **xhtml** files. -### Default pages bundled in the `jans-auth.war` are: +### Default pages bundled in the `jans-auth.war` are: * Login page: [login.xhtml](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/server/src/main/webapp/login.xhtml) * Authorization page: [authorize.xhtml](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/server/src/main/webapp/authorize.xhtml) * Logout page: [logout.xhtml](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/server/src/main/webapp/logout.xhtml) @@ -23,9 +23,9 @@ Put a modified `login.xhtml` or `authorize.xhtml` or `error.xhtml` or `logout.xh | |-- i18n (resource bundles) | |-- libs (library files used by custom script) | |-- pages (web pages) -| |-- static (images and css files) +| |-- static (images and css files) ``` -### Adding a new web page for Person Authentication scripts +### Adding a new web page for Person Authentication scripts 1. If `enterOTP.xhtml` is your webpage for step 2 of authentication, place under `/opt/jans/jetty/jans-auth/custom/pages/enterOTP.xhtml` 2. Reference it in the custom script as follows: ``` @@ -39,10 +39,10 @@ Put a modified `login.xhtml` or `authorize.xhtml` or `error.xhtml` or `logout.xh ### Customized resource bundles: -1. Resource bundles that are present in the jans-auth.war are present in this [folder](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/server/src/main/resources/) +1. Resource bundles that are present in the jans-auth.war are present in this [folder](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/server/src/main/resources/) 2. To override the defaults, custom `.properties` files should be placed in the following file under this path : `/opt/jans/jetty/jans-auth/custom/i18n/jans-auth.properties` -Resource bundle names to support other languages should be placed under the same folder `/opt/jans/jetty/jans-auth/custom/i18n/`. Some examples of file names are : +Resource bundle names to support other languages should be placed under the same folder `/opt/jans/jetty/jans-auth/custom/i18n/`. Some examples of file names are : * jans-auth_en.properties * jans-auth_bg.properties * jans-auth_de.properties @@ -70,4 +70,6 @@ Templates refers to the common interface layout and style. For example, a same b 1. `mkdir -p /opt/jans/jetty/jans-auth/custom/pages/WEB-INF/incl/layout/` 2. Place a modified `template.xhtml` in the above location which will override the [default template file](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/server/src/main/webapp/WEB-INF/incl/layout/template.xhtml) from the war +### Example pages: +[Here](https://github.com/JanssenProject/jans/tree/main/jans-auth-server/server/src/main/webapp/auth) you will find several login pages for different authentication methods. diff --git a/docs/admin/developer/interception-scripts.md b/docs/admin/developer/interception-scripts.md index 7badf5501d3..3f8e2630e42 100644 --- a/docs/admin/developer/interception-scripts.md +++ b/docs/admin/developer/interception-scripts.md @@ -196,7 +196,7 @@ where is the name of the library to install. ### Debugging a Jython script -This [article](https://github.com/JanssenProject/jans/blob/main/docs/admin/developer/interception-scripts-debug) covers the details. +This [article](../interception-scripts-debug) covers the details. *** diff --git a/docs/admin/developer/scripts/person-authentication.md b/docs/admin/developer/scripts/person-authentication.md index 715b71ca4ae..1aae0f69844 100644 --- a/docs/admin/developer/scripts/person-authentication.md +++ b/docs/admin/developer/scripts/person-authentication.md @@ -14,8 +14,8 @@ Typically, a `PersonAuthenticationType` script can be used to: 3. offer Social logins 4. proactively perform fraud detection and block the user. -## Default authentication method: -In an OpenID Connect authentication request, one of the optional parameters defined is `acr_values`. This is the primary way for a client to signal to the OpenID Provider (OP) the preferred way to authenticate the subject. +## Default authentication method: +In an OpenID Connect authentication request, one of the optional parameters defined is `acr_values`. This is the primary way for a client to signal to the OpenID Provider (OP) the preferred way to authenticate the subject. A client may also specify `default_acr_values` during registration (and omit the parameter while making an authentication request). **In the Jansssen Server configuration, `acr` is used to name the authentication workflow.** `default_acr`: This is the default authentication mechanism exposed to all applications that send users to the Janssen Server for sign-in. Unless an app specifically requests a different form of authentication using the OpenID Connect acr_values parameter (as specified below), users will receive the form of authentication specified in this field. @@ -30,14 +30,14 @@ The Jans Server can concurrently support multiple authentication mechanisms, ena ### Enabling an authentication mechanism By default, users will get the default authentication mechanism as specified above. However, **using the OpenID Connect acr_values parameter, web and mobile clients can request any enabled authentication mechanism**. -1. Obtain the json contents of a custom script by using a jans-cli command like `get-config-scripts-by-type`, `get-config-scripts-by-inum` etc. - Example : +1. Obtain the json contents of a custom script by using a jans-cli command like `get-config-scripts-by-type`, `get-config-scripts-by-inum` etc. + Example : - `/opt/jans/jans-cli/config-cli.py --operation-id get-config-scripts-by-type --url-suffix type:PERSON_AUTHENTICATION` - `/opt/jans/jans-cli/config-cli.py --operation-id get-config-scripts-by-inum --url-suffix inum:6122281b-b55d-4dd0-8115-b098eeeee2b7` 2. [Update the custom script](https://github.com/JanssenProject/jans-cli/blob/main/docs/cli/cli-custom-scripts.md#update-an-existing-custom-script) and change the `enabled` attribute to `true` -### Level (rank) of an Authentication mechanism : +### Level (rank) of an Authentication mechanism : Each authentication mechanism has a "Level" assigned to it which describes how secure and strict it is. **The higher the "Level", the more reliable mechanism represented by the script is.** Though several mechanisms can be enabled at the same Janssen server instance at the same time, for any specific user's session only one of them can be set as the current one (and will be returned as `acr` claim of id_token for them). If after initial session is created a new authorization request from a RP comes in specifying another authentication method, its "Level" will be compared to that of the method currently associated with this session. If requested method's "Level" is lower or equal to it, nothing is changed and the usual SSO behavior is observed. If it's higher (i.e. a more secure method is requested), it's not possible to serve such request using the existing session's context, and user must re-authenticate themselves to continue. If they succeed, a new session becomes associated with that requested mechanism instead. Enabled scripts can be confirmed by checking the Janssen OP configuration URL, `https:///.well-known/openid-configuration`, and finding the "**acr_values_supported**". @@ -47,16 +47,16 @@ Learn more about acr_values in the [OpenID Connect core spec](http://openid.net/ ## Building blocks of an authentication workflow -Jans-auth comprises of a number of beans, configuration files and Facelets (JSF) views, packaged as a WAR module. That means custom scripts and custom pages (JSF facelets) can make use of business logic already encapsulated in the Weld managed beans. The following sections explain how authentication flow can be built using a custom script. +Jans-auth comprises of a number of beans, configuration files and Facelets (JSF) views, packaged as a WAR module. That means custom scripts and custom pages (JSF facelets) can make use of business logic already encapsulated in the Weld managed beans. The following sections explain how authentication flow can be built using a custom script. ### A. Writing a custom script The **PersonAuthenticationType** script is described by a java interface whose methods should be overridden to implement an authentication workflow. -The [article](https://jans.io/docs/admin/developer/scripts/person-authentication-interface) talks about these methods in detail and the psuedo code in each method will help drive home the point. - +The [article](./person-authentication-interface) talks about these methods in detail and the psuedo code in each method will help drive home the point. + ### B. Writing UI pages: -All pages are **xhtml** files. The Jans-auth server comes with a default set of pages for login, logout, errors, authorizations. You can easily override these pages or write new ones. You can easily apply your own stylesheet, images and resouce-bundles to your pages. +All pages are **xhtml** files. The Jans-auth server comes with a default set of pages for login, logout, errors, authorizations. You can easily override these pages or write new ones. You can easily apply your own stylesheet, images and resouce-bundles to your pages. -This [article](https://github.com/maduvena/jans-docs/wiki/Writing-UI-pages) covers all the details you need to write your own web page. +This [article](../../customization/customize-web-pages) covers all the details you need to write your own web page. ### C. Building business logic in Custom script: Jans-auth server uses Weld 3.0 (JSR-365 aka CDI 2.0) for managed beans. The most important aspects of business logic are implemented through a set of beans. Details and examples of this can be found in this [article](../managed-beans.md) @@ -70,12 +70,12 @@ More details of this mentioned [here](../interception-scripts.md#using-python-li ### A. Implementing 2FA authentication mechanisms 1. [FIDO2](../../../script-catalog/person_authentication/fido2-external-authenticator/README) : Authentications using platform authenticators embedded into a person's device or physical USB, NFC or Bluetooth security keys that are inserted into a USB slot of a computer 2. SMS OTP : -3. Email OTP +3. Email OTP ### B. Implementing Multistep authentication -1. [Redirect to previous step](https://github.com/JanssenProject/jans/blob/main/jans-linux-setup/jans_setup/static/extension/person_authentication/other/basic.reset_to_step/BasicResetToStepExternalAuthenticator.py): The script here an example of how the number of steps can be varied depending on the context or business requirement. +1. [Redirect to previous step](https://github.com/JanssenProject/jans/blob/main/jans-linux-setup/jans_setup/static/extension/person_authentication/other/basic.reset_to_step/BasicResetToStepExternalAuthenticator.py): The script here an example of how the number of steps can be varied depending on the context or business requirement. -### C. Implementing Social logins +### C. Implementing Social logins You can use a `PersonAuthenticationType` script to allow users to sign using credentials from popular **Social Identity providers** or **Inbound Identity Providers** like Facebook, Google and Apple. After users authenticate, thier Social Identity Provider credentials are provisioned into the Jans-auth server. More on this topic in this [article](../../recipes/social-login.md) ### D. Proactively perform fraud detection @@ -83,9 +83,9 @@ You can use a `PersonAuthenticationType` script to allow users to sign using cre ## Testing an authentication flow -An example of a complete URL looks like this - +An example of a complete URL looks like this - ``` - + https:///jans-auth/authorize.htm? \ response_type=code&redirect_uri=https:///admin \ &client_id=17b8b82e-b3ec-42a2-bd90-097028a37f3 \ @@ -97,14 +97,14 @@ To test , enter the complete URL for authorization in a browser or create a simp ## FAQs ### 1. How can error messages be displayed on a web page? -1. FacesMessage bean is used for this purpose. +1. FacesMessage bean is used for this purpose. ``` from org.jans.jsf2.message import FacesMessages from org.jans.service.cdi.util import CdiUtil from javax.faces.application import FacesMessage ... - facesMessages = CdiUtil.bean(FacesMessages) + facesMessages = CdiUtil.bean(FacesMessages) facesMessages.setKeepMessages() facesMessages.add(FacesMessage.SEVERITY_ERROR, "Please enter a valid username") @@ -117,7 +117,7 @@ To test , enter the complete URL for authorization in a browser or create a simp ``` See an example [here](https://github.com/JanssenProject/jans/blob/685a1593fb53e2310cfa38fcd49db94f3453042f/jans-auth-server/server/src/main/webapp/WEB-INF/incl/layout/template.xhtml#L41) -### 2. How is redirection to a third party application for authentication handled in a script? +### 2. How is redirection to a third party application for authentication handled in a script? For user authentication or consent gathering, there might be a need to redirect to a third party application to perform some operation and return the control back to authentication steps of the custom script. Please apply these steps to a person authentication script in such a scenario: @@ -159,11 +159,11 @@ So create an xhtml page postlogin.xhtml which will look like this : ``` -The `` in step 4 takes us to the authenticate method inside the custom script `def authenticate(self, configurationAttributes, requestParameters, step):`. Here you can +The `` in step 4 takes us to the authenticate method inside the custom script `def authenticate(self, configurationAttributes, requestParameters, step):`. Here you can - use parameters from request ``` - param = ServerUtil.getFirstValue(requestParameters, "param-name")) - ``` + param = ServerUtil.getFirstValue(requestParameters, "param-name")) + ``` - perform the `state` check (state : Opaque value used to maintain state between the request and the callback.) - finally, return true or false from this method.