diff --git a/docs/admin/developer/agama/samples.md b/docs/admin/developer/agama/samples.md index 7cbdc9598c3..054560ad44f 100644 --- a/docs/admin/developer/agama/samples.md +++ b/docs/admin/developer/agama/samples.md @@ -35,7 +35,7 @@ Source code [here](https://github.com/JanssenProject/jans/raw/main/docs/admin/de ### UI template -[`login.ftlh`](https://github.com/JanssenProject/jans/raw/main/docs/admin/developer/agama/basic/login.ftlh) is 99% HTML markup and will not be detailed here. There are only a couple of things to highlight: +[`login.ftlh`](https://github.com/JanssenProject/jans/raw/main/docs/admin/developer/agama/basic/login.ftlh) is 99% HTML markup and will not be detailed here. There are only a couple of things to highlight: - The conditional `<#if !(success!true)>` (around line 27) is used to determine if an error message should be included in the generated markup. It works this way: if the key `success` exists in this template data model, its value is negated (note the bang character before the left parenthesis) and the `if` condition is evaluated. If non-existing, a `true` value is assumed which is then negated and thus the `if` body will not be evaluated- diff --git a/docs/script-catalog/agama/inboundID/README.md b/docs/script-catalog/agama/inboundID/README.md index cb5d93609bc..61d36cdd231 100644 --- a/docs/script-catalog/agama/inboundID/README.md +++ b/docs/script-catalog/agama/inboundID/README.md @@ -35,10 +35,10 @@ Note the scope here is limited: no session is created in the Janssen server for To facilitate administrators' work, the following flows are already implemented: -- Apple -- [Facebook](https://github.com/JanssenProject/jans/tree/main/docs/script-catalog/agama/inboundID/facebook) -- [Github](https://github.com/JanssenProject/jans/tree/main/docs/script-catalog/agama/inboundID/github) -- [Google](https://github.com/JanssenProject/jans/tree/main/docs/script-catalog/agama/inboundID/google) +- [Apple](./apple/README.md) +- [Facebook](./facebook) +- [Github](./github) +- [Google](./google) ### Main flow @@ -71,19 +71,28 @@ To start, let's add the required libraries to the authentication server: - Navigate to `/opt/jans/jetty/jans-auth/webapps` and edit the file `jans-auth.xml` by adding `./custom/libs/*` before the root tag closes - Restart the server, e.g. `systemctl restart jans-auth` -### Add the main inbound flow +### Add the basic authentication flow + +The basic authentication flow is employed when no provider is picked from the list (step 1 [here](#main-flow)) but the option to use an existing local account is taken. This flow is detailed in the Agama sample flows [page](https://jans.io/docs/admin/developer/agama/samples/#basic-authentication), however those contents can be skipped for the purpose of this setup. -- Ensure Agama engine is [enabled](https://jans.io/docs/admin/developer/agama/quick-start/#enable-the-engine). Download the flow [source](https://github.com/JanssenProject/jans/raw/main/docs/script-catalog/agama/inboundID/io.jans.inbound.ExternalSiteLogin) file +- Ensure Agama engine is [enabled](https://jans.io/docs/admin/developer/agama/quick-start/#enable-the-engine). Download the basic flow [source](https://github.com/JanssenProject/jans/raw/main/docs/admin/developer/agama/basic/io.jans.flow.sample.basic) file - Use the API for adding flows as explained [here](https://jans.io/docs/admin/developer/agama/quick-start/#getting-an-access-token) and [here](https://jans.io/docs/admin/developer/agama/quick-start/#add-the-flow-to-the-server). A sample `curl` command would look like this: ``` curl -k -i -H 'Authorization: Bearer ' -H 'Content-Type: text/plain' - --data-binary @io.jans.inbound.ExternalSiteLogin - https:///jans-config-api/api/v1/agama/io.jans.inbound.ExternalSiteLogin + --data-binary @io.jans.flow.sample.basic + https:///jans-config-api/api/v1/agama/io.jans.flow.sample.basic ``` +- In the server, navigate to `/opt/jans/jetty/jans-auth/agama/ftl`. Create the folder hierarchy `samples/basic` there + +- Download the login [template](https://github.com/JanssenProject/jans/raw/main/docs/admin/developer/agama/basic/login.ftlh) to `basic` directory + +### Add the main inbound flow + +- Download the flow [source](https://github.com/JanssenProject/jans/raw/main/docs/script-catalog/agama/inboundID/io.jans.inbound.ExternalSiteLogin) and add it as you did with the basic flow, ensure you use `io.jans.inbound.ExternalSiteLogin` this time -- In the server, navigate to `/opt/jans/jetty/jans-auth/agama/`. Create folders named `inboundID` inside existing `ftl` and `fl` subdirectories +- In the server, navigate to `/opt/jans/jetty/jans-auth/agama`. Create folders named `inboundID` inside existing `ftl` and `fl` subdirectories - Download the default [logo](https://github.com/JanssenProject/jans/raw/main/docs/script-catalog/agama/inboundID/none.png) and place it inside `/opt/jans/jetty/jans-auth/agama/fl/inboundID` folder @@ -216,7 +225,7 @@ The table below explains the meaning of properties: ### Provider flow configurations -Configurations for this kind of flows don't have to adhere to any specific structure. Developers are free to choose what fits best for their needs. Also note provider flows **must not** receive any inputs: the main flow won't pass any arguments when triggering them. Thus, design your flows so there is no use of `Inputs` but `Configs` directive in the [header](https://jans.io/docs/admin/developer/agama/dsl-full/#header-basics) . +Configurations for this kind of flows don't have to adhere to any specific structure. Developers are free to choose what fits best for their needs. Also note provider flows **must not** receive any inputs: the main flow won't pass any arguments when triggering them. Thus, design your flows so there is no use of `Inputs` but `Configs` directive in the [header](https://jans.io/docs/admin/developer/agama/dsl-full/#header-basics). In practice many identity providers adhere to the OAuth2 `code` grant, so you can re-use the structure represented by [this](https://github.com/JanssenProject/jans/blob/main/agama/inboundID/src/main/java/io/jans/inbound/oauth2/OAuthParams.java) Java class for the purpose. Particularly, the already implemented flows (like Facebook) use it for their configuration. diff --git a/docs/script-catalog/agama/inboundID/apple/README.md b/docs/script-catalog/agama/inboundID/apple/README.md new file mode 100644 index 00000000000..925d1523c5e --- /dev/null +++ b/docs/script-catalog/agama/inboundID/apple/README.md @@ -0,0 +1,74 @@ +# The "Sign In With Apple" Agama flow + +To deploy this flow, a number of configurations are required. Ensure you have an Apple developer account to start. [This tutorial](https://github.com/ananay/apple-auth/blob/master/SETUP.md) does a great job at explaining the necessary steps. As you go with it, ensure you collect the following elements: + +- A service ID +- A team ID +- A key ID and a key file + +You will be prompted to provide a domain name and a return URL. Provide `` and `https:///jans-auth/fl/callback` respectively, ensuring the changes are effectively saved in the developer's portal. + +Please follow the [inbound identity guide](../README.md) **entirely** before proceeding. + +## Flow and assets + +Find this flow source code [here](https://github.com/JanssenProject/jans/raw/main/docs/script-catalog/agama/inboundID/apple/io.jans.inbound.Apple). Copy the [logo](https://github.com/JanssenProject/jans/raw/main/docs/script-catalog/agama/inboundID/apple/apple.png) to your server at `/opt/jans/jetty/jans-auth/agama/fl/inboundID`, if desired. + +## Supply configurations + +Create a json fragment using the below as a guide: + +``` +{ + "authzEndpoint": "https://appleid.apple.com/auth/authorize", + "tokenEndpoint": "https://appleid.apple.com/auth/token", + "clientId": "", + "key": "", + "keyId": "", + "teamId": "", + "scopes": ["email", "name"], + "custParamsAuthReq": { "response_mode": "form_post" }, + "clientCredsInRequestBody": true +} +``` + +For the `key`, remove the lines regarding begin/end of the private key entirely. Also remove any line breaks: a one-liner is required. + +Use the crafted JSON content to parameterize this flow, as in [Set configuration parameters](../README.md#set-configuration-parameters). + +Then use the below to [parameterize the main flow](../README.md#parameterize-the-main-flow): + +``` +"apple": { + "flowQname": "io.jans.inbound.Apple", + "displayName": "Apple", + "mappingClassField": "io.jans.inbound.Mappings.APPLE", + "logoImg": "apple.png" +} +``` + +## Expected journey + +The accompanying images illustrate the steps end-users will go through when using the inbound identity flow taking the Apple route: + +*Initial provider selector page* + +![provider selector](provider_selector.png) + +*Prompt for credentials at Apple website* + +![prompt credentials](SIWA_creds.png) + +*Prompt for a second factor, e.g. SMS (optional)* + +![prompt second factor](SIWA_MFA.png) + +*Prompt for browser trust* + +![browser trust](SIWA_trust.png) + +*Prompt to before returning to original site* + +![prompt continue](SIWA_proceed.png) + +Finally, the user should land at the target application. diff --git a/docs/script-catalog/agama/inboundID/apple/SIWA_MFA.png b/docs/script-catalog/agama/inboundID/apple/SIWA_MFA.png new file mode 100644 index 00000000000..037b1660943 Binary files /dev/null and b/docs/script-catalog/agama/inboundID/apple/SIWA_MFA.png differ diff --git a/docs/script-catalog/agama/inboundID/apple/SIWA_creds.png b/docs/script-catalog/agama/inboundID/apple/SIWA_creds.png new file mode 100644 index 00000000000..830856be208 Binary files /dev/null and b/docs/script-catalog/agama/inboundID/apple/SIWA_creds.png differ diff --git a/docs/script-catalog/agama/inboundID/apple/SIWA_proceed.png b/docs/script-catalog/agama/inboundID/apple/SIWA_proceed.png new file mode 100644 index 00000000000..3cb839a9aad Binary files /dev/null and b/docs/script-catalog/agama/inboundID/apple/SIWA_proceed.png differ diff --git a/docs/script-catalog/agama/inboundID/apple/SIWA_trust.png b/docs/script-catalog/agama/inboundID/apple/SIWA_trust.png new file mode 100644 index 00000000000..224eda9e2be Binary files /dev/null and b/docs/script-catalog/agama/inboundID/apple/SIWA_trust.png differ diff --git a/docs/script-catalog/agama/inboundID/apple/provider_selector.png b/docs/script-catalog/agama/inboundID/apple/provider_selector.png new file mode 100644 index 00000000000..83992db4781 Binary files /dev/null and b/docs/script-catalog/agama/inboundID/apple/provider_selector.png differ