Skip to content

Commit f30dde1

Browse files
arnaud4darnaud4d
committed
Update doc 21
1 parent 74c3823 commit f30dde1

File tree

3 files changed

+155
-12
lines changed

3 files changed

+155
-12
lines changed

‎Documentation/Classes/JWT.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# JWT Class
2+
3+
## Overview
4+
5+
The `JWT` class allows you to generate, decode, and validate JSON Web Tokens (JWTs) to authenticate users and secure API calls. JWTs are widely used in modern web authentication systems, including OAuth2 and OpenID Connect.
6+
7+
This class is typically used in three scenarios:
8+
9+
* **Token generation**: Create a signed JWT when a user logs in.
10+
* **Token decoding**: Read and inspect a JWT received from an authentication provider.
11+
* **Token validation**: Verify the JWT’s signature and expiration before granting access to protected resources.
12+
13+
This class is instantiated using the `cs.NetKit.JWT.new()` function.
14+
15+
**Note:** Shared objects are not supported by the 4D NetKit API.
16+
17+
## Table of contents
18+
19+
* [cs.NetKit.JWT.new()](#csnetkitjwtnew)
20+
* [JWT.decode()](#jwtdecode)
21+
* [JWT.generate()](#jwtgenerate)
22+
* [JWT.validate()](#jwtvalidate)
23+
24+
25+
## cs.NetKit.JWT.new()
26+
27+
**cs.NetKit.JWT.new** ( *key* : Text or Object ) : `cs.NetKit.JWT`
28+
29+
Creates a new instance of the JWT class.
30+
31+
### Parameters
32+
33+
| Parameter | Type | Description |
34+
|-----------|--------------|-------------|
35+
| key | Text/Object | *Optional.* If text → Key in PEM format.<br>- If object → Must be an object returned by `4D.CryptoKey`.<br>If it's a private key, the public key will be inferred. |
36+
37+
### Example
38+
39+
```4d
40+
var $jwt := cs.NetKit.JWT.new($key)
41+
42+
```
43+
44+
## JWT.decode()
45+
46+
**JWT.decode** ( *token* : Text ) : Object
47+
48+
### Parameters
49+
50+
| Parameter | Type | | Description |
51+
|-----------|----- |:---:|----------------- |
52+
| token | Text |->| JWT string to decode |
53+
| Result | Object |<-|The decoded content of the JWT |
54+
55+
### Description
56+
57+
Decodes a JWT string and returns its components (header, payload, signature).
58+
59+
### Returned object
60+
61+
The function returns an object containing the following properties:
62+
63+
| Property | Type | Description |
64+
|---|---|---|
65+
|header| Object |Metadata about the token type and the signing algorithm |
66+
|payload| Object |The information (claims) of the token like the user's name, role, user ID, or expiration date.|
67+
|signature| Object |Ensures the integrity of the token and verifies the sender’s authenticity|
68+
69+
### Example
70+
71+
```4d
72+
73+
var $result := cs.NetKit.JWT.new().decode($token)
74+
75+
```
76+
77+
## JWT.generate()
78+
79+
**JWT.generate** ( *params* : Object { ; *privateKey* : Text or Object } ) : Text
80+
81+
### Parameters
82+
83+
| Parameter | Type | | Description |
84+
|------------|--------|:--:|--------------------------------------------------------------|
85+
| params | Object | ->| Options for the JWT content|
86+
| privateKey | Text/Object | ->| *Optional.* If text → Private key in PEM format.<br>- If object → Must be returned by `4D.CryptoKey`.<br>If omitted, the key passed to `JWT.new()` will be used. |
87+
| Result | Text | <-| The generated JWT token |
88+
89+
### Description
90+
91+
Generates a signed JWT based on the provided parameters and optional private key.
92+
93+
In *params*, you can pass several properties:
94+
95+
| Property | | Type | Description |
96+
|----------|--|------|-------------|
97+
| header | |Object | *(optional)* Metadata about the token |
98+
| | header.alg |Text |Signing algorithm. Defaults to `"RS256"` if not specified |
99+
| | header.typ |Text | Token type. Defaults to `"JWT"` if not specified|
100+
| payload | | Object | The claims/information you want to include in the token|
101+
102+
### Example
103+
104+
```4d
105+
106+
var $params:={header: {alg: "HS256"; typ: "JWT"}}
107+
$params.payload:={sub: "123456789"; name: "John"; exp : 50}
108+
109+
var $token := cs.NetKit.JWT.new().generate($params; $privateKey)
110+
111+
```
112+
113+
## JWT.validate()
114+
115+
**JWT.validate** ( *token* : Text { ; *key* : Text or Object } ) : Boolean
116+
117+
### Parameters
118+
119+
| Parameter | Type | | Description |
120+
|-----------|------|--:|-------------------------------------------------------------|
121+
| token | Text | ->| JWT token to validate |
122+
| key | Text | ->| *Optional.* If text → Private or public key in PEM format.<br>- If object → Must be returned by `4D.CryptoKey`.<br>If omitted, the key passed to `JWT.new()` will be used. |
123+
| Result | Boolean | <-| `True` if the token is valid, `False` otherwise |
124+
125+
### Description
126+
127+
Validates a JWT token using the provided public key or the key passed to the constructor.
128+
129+
### Example
130+
131+
```4d
132+
133+
var $isValid:= cs.NetKit.JWT.new().validate($token; $key)
134+
135+
```
136+
## See also
137+
138+
* [OAuth2Provider Class](./OAuth2Provider.md)
139+
* [Google Class](./Google.md)
140+
* [Office365 Class](./Office365.md)
141+
142+

‎Documentation/Classes/OAuth2Provider.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -50,31 +50,31 @@ The available properties of `paramObj` are:
5050

5151
|Parameter|Type|Description|Optional|
5252
|---------|--- |------|------|
53-
| accessType | text | (Recommended) Indicates whether your application can refresh access tokens when the user is not present at the browser.&lt;br/&gt; Valid parameter values are online (default) and offline.&lt;br/&gt; Set the value to offline if your application needs to update access tokens when the user is not present at the browser. This is how access tokens are refreshed. This value instructs the Google authorization server to return a refresh token and an access token the first time that your application exchanges an authorization code for tokens. |Yes|
54-
| authenticateURI | text | Uri used to do the Authorization request.&lt;br/&gt; Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize".&lt;br/&gt; Default for Google: "https://accounts.google.com/o/oauth2/auth". |Yes|
55-
| authenticationErrorPage |text or file object| Path of the web page to display in the web browser when the authentication server returns an error in signed in mode (If not present the default page is used).|Yes|
56-
| authenticationPage|text or file object|Path of the web page to display in the web browser when the authentication code is received correctly in signed in mode (If not present the default page is used).|Yes|
53+
| accessType | text | (Recommended) Indicates whether your application can refresh access tokens when the user is not present at the browser.<br/> Valid parameter values are online (default) and offline.<br/> Set the value to offline if your application needs to update access tokens when the user is not present at the browser. This is how access tokens are refreshed. This value instructs the Google authorization server to return a refresh token and an access token the first time that your application exchanges an authorization code for tokens. |Yes|
54+
| authenticateURI | text | Uri used to do the Authorization request.<br/> Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize".<br/> Default for Google: "https://accounts.google.com/o/oauth2/auth". |Yes|
55+
| authenticationErrorPage |text or file object|A local file object, local path or direct URL of the page to display in the web browser when authentication fails in signedIn mode. Can be a Qodly URL. If not provided, the default page is used.|Yes|
56+
| authenticationPage|text or file object|A local file object, local path or a direct URL of the page to display in the web browser after successful authentication in signedIn mode. Can be a Qodly URL. If not provided, the default page is used.|Yes|
5757
| browserAutoOpen | boolean | True (default value), the web browser is open automatically. Pass false if you don't want the web browser to open automatically. |Yes|
5858
| clientAssertionType | text | The format of the assertion as defined by the authorization server. The value is an absolute URI. Default value: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer". Only usable with permission="Service" |Yes|
5959
| clientEmail | text | (mandatory, Google / service mode only) email address of the service account used |No|
6060
| clientId | text | The client ID assigned to the app by the registration portal.|No|
6161
| clientSecret | text | The application secret that you created for your app in the app registration portal. Required for web apps. |Yes|
62-
| loginHint | text | (Optional) This option can be used to inform the Google Authentication Server which user is attempting to authenticate if your application is aware of this information. By prefilling the email field in the sign-in form or by selecting the appropriate multi-login session, the server uses the hint to simplify the login flow either.&lt;br/&gt; Set the parameter value to a sub-identifier or email address that corresponds to the user's Google ID. |Yes|
62+
| loginHint | text | (Optional) This option can be used to inform the Google Authentication Server which user is attempting to authenticate if your application is aware of this information. By prefilling the email field in the sign-in form or by selecting the appropriate multi-login session, the server uses the hint to simplify the login flow either.<br/> Set the parameter value to a sub-identifier or email address that corresponds to the user's Google ID. |Yes|
6363
| name | text | Name of the provider. Available values: "Microsoft", "Google" or "" (if "" or undefined/null attribute, the authenticateURI and the tokenURI need to be filled by the 4D developer).|Yes|
6464
| nonce | text | Used for *openID* requests only. Value used to associate a client session with an `id_token`, to mitigate replay attacks. The value is passed through unmodified from the Authentication request to the `id_token`.|Yes|
65-
| permission | text |- "signedIn": Azure AD/Google will sign in the user and ensure they gave their consent for the permissions your app requests (opens a web browser).&lt;br/&gt;- service": the app calls [Microsoft Graph with its own identity](https://docs.microsoft.com/en-us/graph/auth-v2-servicean| false by default. If true, PKCE is used for OAuth 2.0 authentication and token requests and is only usable for permission="SignIn". |Yes|
65+
| permission | text |- "signedIn": Azure AD/Google will sign in the user and ensure they gave their consent for the permissions your app requests (opens a web browser).<br/>- service": the app calls [Microsoft Graph with its own identity](https://docs.microsoft.com/en-us/graph/auth-v2-servicean). False by default. If true, PKCE is used for OAuth 2.0 authentication and token requests and is only usable for permission="SignIn". |Yes|
6666
| PKCEMethod |text | "S256" by default. The only supported values for this parameter are "S256" or "plain". |Yes|
67-
| privateKey | text | Certificate private key. Only usable with permission="Service".&lt;br/&gt;(Google / service mode only) Private key given by Google. Mandatory if .permission="service" and .name="Google" | Yes (No for certificate based authentication)|
68-
| prompt | text |(Optional) A space-delimited, case-sensitive list of prompts to present the user.&lt;br/&gt;&lt;br/&gt;Possible values are:&lt;br/&gt;- none: Do not display any authentication or consent screens. Must not be specified with other values.&lt;br/&gt;- consent: Prompt the user for consent.&lt;br/&gt;- select_account: Prompt the user to select an account.&lt;br/&gt;(if you don't specify this parameter, the user will be prompted only the first time your project requests access. )|Yes|
67+
| privateKey | text | Certificate private key. Only usable with permission="Service".<br/>(Google / service mode only) Private key given by Google. Mandatory if .permission="service" and .name="Google" | Yes (No for certificate based authentication)|
68+
| prompt | text |(Optional) A space-delimited, case-sensitive list of prompts to present the user.<br/><br/>Possible values are:<br/>- none: Do not display any authentication or consent screens. Must not be specified with other values.<br/>- consent: Prompt the user for consent.<br/>- select_account: Prompt the user to select an account.<br/>(if you don't specify this parameter, the user will be prompted only the first time your project requests access. )|Yes|
6969
| redirectURI | text | (Not used in service mode) The redirect_uri of your app, i.e. the location where the authorization server sends the user once the app has been successfully authorized. Depending on the port specified in this property, the authentication response goes to the [web server of the host or of the 4DNetKit when you call the `.getToken()` class function. |No in signedIn mode, Yes in service mode|
70-
| scope | text or collection | Text: A space-separated list of the Microsoft Graph or Google permissions that you want the user to consent to.&lt;/br&gt; Collection: Collection of Microsoft Graph or Google permissions. |Yes|
70+
| scope | text or collection | Text: A space-separated list of the Microsoft Graph or Google permissions that you want the user to consent to.<br/> Collection: Collection of Microsoft Graph or Google permissions. |Yes|
7171
| state | text | Opaque value used to maintain state between the request and the callback. If not present, automatically generated by 4D Netkit. |Yes|
72-
| tenant | text | Microsoft: The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are: - "common" for both Microsoft accounts and work or school accounts (default value)&lt;br/&gt;- "organizations" for work or school accounts only &lt;br/&gt;- "consumers" for Microsoft accounts only&lt;br/&gt;- tenant identifiers such as tenant ID or domain name.&lt;br/&gt;Google (service mode only): Email address to be considered as the email address of the user for which the application is requesting delegated access. |Yes|
72+
| tenant | text | Microsoft: The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are: - "common" for both Microsoft accounts and work or school accounts (default value)<br/>- "organizations" for work or school accounts only <br/>- "consumers" for Microsoft accounts only<br/>- tenant identifiers such as tenant ID or domain name.<br/>Google (service mode only): Email address to be considered as the email address of the user for which the application is requesting delegated access. |Yes|
7373
| thumbprint |text | Certificate thumbprint. Only usable with permission="Service" | Yes (No for certificate based authentication)|
7474
| timeout|real| Waiting time in seconds (by default 120s).|Yes|
7575
| token | object | If this property exists, the `getToken()` function uses this token object to calculate which request must be sent. It is automatically updated with the token received by the `getToken()` function. |Yes|
7676
| tokenExpiration | text | Timestamp (ISO 8601 UTC) that indicates the expiration time of the token.| Yes|
77-
| tokenURI | text | Uri used to request an access token.&lt;br/&gt; Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token".&lt;br/&gt; Default for Google: "https://accounts.google.com/o/oauth2/token".|Yes|
77+
| tokenURI | text | Uri used to request an access token.<br/> Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token".<br/> Default for Google: "https://accounts.google.com/o/oauth2/token".|Yes|
7878

7979

8080

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<div class="footer border-top border-gray-light mt-5 pt-3 text-right text-black">
2-
Version: 20 R10
2+
Version: 21
33
</div>
44
55
# 4D NetKit
@@ -9,6 +9,7 @@
99
## Table of contents
1010

1111
* [OAuth2Provider class](Documentation/Classes/OAuth2Provider.md)
12+
* [JWT class](Documentation/Classes/JWT.md)
1213
* [Office365 class](Documentation/Classes/Office365.md)
1314
* [Google class](Documentation/Classes/Google.md)
1415
* [Tutorial : Authenticate to the Microsoft Graph API in service mode](Documentation/Tutorial.md)

0 commit comments

Comments
 (0)