Skip to content

Commit 5e2fa7b

Browse files
arnaud4darnaud4d
committed
Update OAuth2Provider.md
1 parent ccf03c2 commit 5e2fa7b

File tree

1 file changed

+64
-26
lines changed

1 file changed

+64
-26
lines changed

‎Documentation/Classes/OAuth2Provider.md‎

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

5151
|Parameter|Type|Description|Optional|
5252
|---------|--- |------|------|
53-
| 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
54-
| 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-service)/Google (access without a user).|No
55-
| clientId | text | The client ID assigned to the app by the registration portal.|No
56-
| 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 4D NetKit](#web-server-for-redirect-uri) when you call the [`.getToken()`](#oauth2providerobjectgettoken) class function. |No in signedIn mode, Yes in service mode
57-
| scope | text or collection | Text: A space-separated list of the Microsoft Graph permissions that you want the user to consent to.</br> Collection: Collection of Microsoft Graph permissions. |Yes
58-
| 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
59-
| 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
60-
| 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
61-
|tokenExpiration | text | Timestamp (ISO 8601 UTC) that indicates the expiration time of the token.| Yes
62-
| clientSecret | text | The application secret that you created for your app in the app registration portal. Required for web apps. |Yes
63-
| 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
64-
| timeout|real| Waiting time in seconds (by default 120s).|Yes
65-
| 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|
66-
| 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|
67-
| 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|
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|
57+
| 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|
58+
| 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|
6859
| clientEmail | text | (mandatory, Google / service mode only) email address of the service account used |No|
69-
| 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
70-
| 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
71-
| PKCEEnabled |boolean| false by default. If true, PKCE is used for OAuth 2.0 authentication and token requests and is only usable for permission=”SignIn”. |Yes
72-
| PKCEMethod |text | "S256" by default. The only supported values for this parameter are "S256" or "plain". |Yes
73-
| thumbprint |text | Certificate thumbprint. Only usable with permission="Service" | Yes (No for certificate based authentication)
74-
| 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)
75-
| 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
76-
| 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
60+
| clientId | text | The client ID assigned to the app by the registration portal.|No|
61+
| 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|
63+
| 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|
64+
| 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|
66+
| 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|
69+
| 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|
71+
| 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|
73+
| thumbprint |text | Certificate thumbprint. Only usable with permission="Service" | Yes (No for certificate based authentication)|
74+
| timeout|real| Waiting time in seconds (by default 120s).|Yes|
75+
| 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|
76+
| 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|
78+
79+
7780

7881
If you want the .getToken() function to use the Assertion Framework described in the RFC 7521 to connect to the server, make sure to pass the `thumbprint` and `privateKey` properties. If `clientSecret`, `thumbprint` and `privateKey` are present, the `thumbprint` is used by default and the RFC 7521 is used to connect. For more information, please refer to the [OAuth2.0 authentication using a certificate](#https://blog.4d.com/) blog post.
7982

83+
84+
8085
**Note:** The `authenticationPage` and `authenticationErrorPage` and all the resources associated must be in the same folder.
8186

8287
### Web server for redirect URI
@@ -240,6 +245,37 @@ $myCurrentToken:=$OAuth.getToken()
240245

241246
**Note**: Some servers, like Google, do not always return the refresh token during subsequent token requests. In such cases, you should remember to include the refresh token in the token object before saving it for future use.
242247

248+
### Example 4
249+
250+
This example shows how to handle an "id_token" for an openID authentication.
251+
252+
```4d
253+
254+
var $provider:={}
255+
$provider.name:="Microsoft"
256+
$provider.permission:="signedIn"
257+
$provider.clientId:="xxxx"
258+
$provider.redirectURI:="http://127.0.0.1:80/authorize/"
259+
$provider.scope:="openid profile email" // request identity and profile info
260+
$provider.nonce:="randomNonce456" // optional custom nonce value
261+
262+
var $oauth:=cs.NetKit.OAuth2Provider.new($provider)
263+
var $token:=$oauth.getToken()
264+
265+
// Access the id_token
266+
If ($token.token.id_token#Null)
267+
268+
// Deserialize the JWT result with cs.NetKit.JWT class
269+
var $openID:=cs.NetKit.JWT.new().decode($token.token.id_token)
270+
271+
If ($openID.payload.nonce=$param.nonce)
272+
ALERT("Hello "+$openID.payload.name)
273+
End if
274+
275+
End if
276+
```
277+
278+
243279
## OAuth2ProviderObject.getToken()
244280

245281
**OAuth2ProviderObject.getToken()** : Object
@@ -257,10 +293,11 @@ Property|Object properties|Type|Description |
257293
|--- |---------| --- |------|
258294
|token||Object| Token returned |
259295
|| expires_in | Text | How long the access token is valid (in seconds). |
260-
|| access_token |Ttext | The requested access token. |
296+
|| access_token |Text | The requested access token. |
261297
|| refresh_token | Text | Your app can use this token to acquire additional access tokens after the current access token expires. Refresh tokens are long-lived, and can be used to retain access to resources for extended periods of time. Available only if the value of the `permission` property is "signedIn". |
262298
|| token_type | Text | Indicates the token type value. The only token type that Azure AD supports is "Bearer". |
263-
||scope|Text| A space separated list of the Microsoft Graph permissions that the access_token is valid for.|
299+
||id_token|text|`id_token` value associated with the authenticated session. Present only for *openID* requests.|
300+
||scope|Text| A space separated list of permissions that the access_token is valid for.|
264301
|tokenExpiration || Text | Timestamp (ISO 8601 UTC) that indicates the expiration time of the token|
265302

266303
If the value of `token` is empty, the command sends a request for a new token.
@@ -277,4 +314,5 @@ In "signedIn" mode, when `.getToken()` is called, a web server included in 4D Ne
277314
## See also
278315

279316
[Google Class](./Google.md)<br/>
280-
[Office365 Class](./Office365.md)
317+
[Office365 Class](./Office365.md)<br/>
318+
[Secure OpenID Authentication with nonce attribute (blog post)](https://blog.4d.com/4d-netkit-secure-openid-authentication-with-nonce-attribute)

0 commit comments

Comments
 (0)