docs: #3036 #3037 (#3038)

JanssenProject · Nov 18, 2022 · 711d09e · 711d09e
1 parent d8e14eb
commit 711d09e
Show file tree

Hide file tree

Showing 2 changed files with 164 additions and 2 deletions.
diff --git a/docs/admin/auth-server/endpoints/device-authorization.md b/docs/admin/auth-server/endpoints/device-authorization.md
@@ -3,7 +3,72 @@ tags:
   - administration
   - auth-server
   - endpoint
+  - device authorization
+  - RFC 8628
+
 ---
 
-This is a placeholder
 
+### Device Authorization endpoint
+The URI to invoke the Device Authorization Endpoint in Janssen Auth Server can be found by checking the introspection_endpoint claim of the OpenID Connect configuration response, typically deployed at `https://<my.jans.server>/.well-known/openid-configuration`
+
+`"device_authorization_endpoint" : "https://<my.jans.server>/jans-auth/restv1/device_authorization"`
+
+### Invoking the endpoint in Device Authorization Flow
+The Device Authorization Grant defined by [RFC 8628](https://tools.ietf.org/html/rfc8628) contains a call to the Device Authorization endpoint in Step 2 of the diagram below. The details of the entire flow can be found in this [article](../oauth-features/device-grant.md)
+
+```mermaid
+sequenceDiagram
+autonumber 1
+    title Oauth2.0 Device Authorization flow
+
+    participant User
+    participant Browser on Computer / Smartphone
+    participant Device App
+    participant Jans AS
+    participant Third Party App
+
+    User->>Device App:Opens an app on device
+    Device App->>Jans AS:Sends authorization request \n"jans-server.com/jans-auth/restv1/device_authorization"
+    Jans AS->>Device App:Response - \nuser_code, device_code, verification_url, interval, expiration
+    Device App ->>User: Instructs the user to access Verification URL \nand enter user_code
+    note over Device App:Device App will keep polling AS for Access Token \nuntil device authorization is completed
+    loop till Device App recieves Access Token:
+    Device App->>Jans AS:request Access Token
+    Jans AS->>Device App:Response - \naccess_denied \nOR expired_token \nOR authorization_pending \nOR Access token
+    end
+    User->>Browser on Computer / Smartphone:Opens a browser \nand access verification URL
+    Browser on Computer / Smartphone->>Jans AS:send user_code to verification URL
+    Jans AS -->> Browser on Computer / Smartphone :Login and authorization prompt
+    Browser on Computer / Smartphone->>Jans AS:Authentication and consent
+    Jans AS->>Jans AS: Mark device as Authorized
+    note over Jans AS:Subsequent polling by the Device App \nwill return an Access Token as indicated \nby the loop above
+    Device App->>Third Party App:Invoke API with Access Token
+    Third Party App->>Device App: return Response
+```
+
+**Request:**
+```
+POST /restv1/device_authorization HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+Host: test.jans.org
+Authorization: Basic MTIzLTEyMy0xMjM6WkE1aWxpTFFDYUR4
+
+client_id=123-123-123&scope=openid+profile+address+email+phone
+```
+**Response:**
+```
+HTTP/1.1 200
+Content-Length: 307
+Content-Type: application/json
+Server: Jetty(9.4.19.v20190610)
+
+{
+    "user_code": "SJFP-DTPL",
+    "device_code": "aeb28bdc90d806ac58d4b0f832f06c3ac9c4bd03292f0c09",
+    "interval": 5,
+    "verification_uri_complete": "https://test.jans.io:8443/device-code?user_code=SJFP-DTPL",
+    "verification_uri": "https://test.jans.io:8443/device-code",
+    "expires_in": 1800
+}
+```
diff --git a/docs/admin/auth-server/endpoints/introspection.md b/docs/admin/auth-server/endpoints/introspection.md
@@ -3,7 +3,104 @@ tags:
   - administration
   - auth-server
   - endpoint
+  - introspection
+  - accessTokenAsJwt
+  - introspectionScriptBackwardCompatibility
 ---
 
-This is a placeholder
+### Introspection endpoint
 
+The URI to invoke the [Introspection Endpoint](https://datatracker.ietf.org/doc/html/rfc7662) in Janssen Auth Server can be found by checking the `introspection_endpoint` claim of the OpenID Connect configuration response, typically deployed at `https://<my.jans.server>/.well-known/openid-configuration`
+
+` "introspection_endpoint" : "https://<my.jans.server>/jans-auth/restv1/introspection" `
+
+#### A. GET:
+
+```
+curl -X 'GET'   'https://<my.jans.server>/jans-auth/restv1/introspection?token=368fea2b-be14-4d30-bd57-bcc4cde2033c&response_as_jwt=false'   -H 'accept: application/json' -H   "Authorization: Bearer 111d51a4-2828-4b47-abce-77034cddcfb5"
+
+```
+Response:
+```
+{
+    "sub": "",
+    "iss": "https://<my.jans.server>",
+    "active": true,
+    "token_type": "Bearer",
+    "client_id": "1800.df1bb233-10b8-40ed-bbb9-07da50892a35",
+    "aud": "1800.df1bb233-10b8-40ed-bbb9-07da50892a35",
+    "nbf": null,
+    "scope": "https://jans.io/oauth/config/scripts.write",
+    "acr_values": null,
+    "cnf": null,
+    "exp": 1668705523,
+    "iat": 1668705223,
+    "jti": null,
+    "username": null
+}
+```
+#### B. POST:
+
+
+Example:
+```
+curl -X 'POST' \
+  'https://<my.jans.server>/jans-auth/restv1/introspection' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -d 'token=eyJra....3ZkB-Ajwg'  
+  -H "Authorization: Bearer eyJra...BpKo7g"
+```
+Response:
+```
+{
+    "sub": "",
+    "iss": "https://<my.jans.server>",
+    "active": true,
+    "token_type": "Bearer",
+    "client_id": "3000.5829c1f8-7554-41ab-a7d6-3513a5e9c4ad",
+    "aud": "3000.5829c1f8-7554-41ab-a7d6-3513a5e9c4ad",
+    "nbf": null,
+    "scope": "",
+    "acr_values": null,
+    "cnf": null,
+    "exp": 1668941216,
+    "iat": 1668781885,
+    "jti": null,
+    "username": null
+}
+```
+
+
+### Customizing the behavior of AS
+
+Configure the Janssen AS using steps explained in the [link](#curl-commands-to-configure-jans-auth-server)
+
+1. As the access token has sufficient entropy, and a short lifetime, authentication should not be required.
+Configure the Janssen AS to reflect `introspectionSkipAuthorization=true` (default value false)
+
+2. In order to be run and Introspection script should be associated with an OpenID Client (used for obtaining the token). Another way of doing this is by setting the ` introspectionScriptBackwardCompatibility` global Auth Server JSON Configuration Property to true. In this case the Auth Server will run all scripts and will do so by ignoring client configuration.
+
+### Introspection interception script
+By using the power [IntrospectionType](https://github.com/JanssenProject/jans/blob/main/jans-core/script/src/main/java/io/jans/model/custom/script/type/introspection/IntrospectionType.java) custom script, one can modify claims of an Access token as JWT. To do this:
+
+1. Configure the Client using steps explained in the [link](#curl-commands-to-configure-jans-auth-server)
+  Update the following parameters for the client
+  - `accessTokenAsJwt = true`
+  - `runIntrospectionScriptBeforeJwtCreation = true`
+
+2. Script
+  [Introspection Script Guide](../../../script-catalog/introspection/README.md)
+
+
+### Testing
+
+1. [Reference](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/client/src/test/java/io/jans/as/client/ws/rs/IntrospectionWsHttpTest.java)
+
+2. Swagger doc - https://github.com/JanssenProject/jans/blob/main/jans-auth-server/docs/swagger.yaml
+
+3. Useful tool - [jwt.io](https://jwt.io/) to inspect a JWT
+
+### References
+
+1. How is UpdateTokenType script different? - [Article](https://github.com/JanssenProject/jans/blob/main/docs/script-catalog/update_token/sample-script/README.md)