From cf7ead03aa389e9d98377e27bd52c3e5935ee813 Mon Sep 17 00:00:00 2001 From: mposolda Date: Thu, 21 Jul 2016 18:58:14 +0200 Subject: [PATCH] KEYCLOAK-3318 Documentation for parameters forwarding from adapter. More docs for prompt and max_age --- SUMMARY.adoc | 1 + topics/oidc/java/params_forwarding.adoc | 32 +++++++++++++++++++++++++ topics/oidc/javascript-adapter.adoc | 8 +++---- 3 files changed, 36 insertions(+), 5 deletions(-) create mode 100644 topics/oidc/java/params_forwarding.adoc diff --git a/SUMMARY.adoc b/SUMMARY.adoc index f5ed52c0e0..9729f18fe2 100644 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -29,6 +29,7 @@ ... link:topics/oidc/java/adapter-context.adoc[Security Context] ... link:topics/oidc/java/adapter_error_handling.adoc[Error Handling] ... link:topics/oidc/java/logout.adoc[Logout] + ... link:topics/oidc/java/params_forwarding.adoc[Parameters Forwarding] ... link:topics/oidc/java/multi-tenancy.adoc[Multi Tenancy] ... link:topics/oidc/java/application-clustering.adoc[Application Clustering] diff --git a/topics/oidc/java/params_forwarding.adoc b/topics/oidc/java/params_forwarding.adoc new file mode 100644 index 0000000000..91c8300717 --- /dev/null +++ b/topics/oidc/java/params_forwarding.adoc @@ -0,0 +1,32 @@ + +==== Parameters Forwarding + +The {{book.project.name}} initial authorization endpoint request has support for various parameters. Most of the parameters are described in +http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[OIDC specification] . Some parameters are added automatically by adapter based +on the adapter configuration. However there are also few parameters, which can be added on per-invocation basis. When you open the secured application URI, +the particular parameter will be forwarded to the {{book.project.name}} authorization endpoint. + +For example, if you request offline token, then you can open the secured application URI with the `scope` parameter like: + +[source] +---- +http://myappserver/mysecuredapp?scope=offline_access +---- + +and the parameter `scope=offline_access` will be automatically forwarded to the {{book.project.name}} authorization endpoint. + +The supported parameters are actually: + +* scope + +* prompt + +* max_age + +* login_hint + +* kc_idp_hint + +Most of the parameters are described in the http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[OIDC specification]. +The only exception is parameter `kc_idp_hint`, which is specific to {{book.project.name}} and contains the name of Identity provider to automatically use. +More info in {{book.adminguide.link}}[{{book.adminguide.name}}] in `Identity Brokering` section. diff --git a/topics/oidc/javascript-adapter.adoc b/topics/oidc/javascript-adapter.adoc index 029a510afe..8ea168e0b8 100644 --- a/topics/oidc/javascript-adapter.adoc +++ b/topics/oidc/javascript-adapter.adoc @@ -255,7 +255,8 @@ Redirects to login form on (options is an optional object with redirectUri and/o Options is an Object, where: * redirectUri - Specifies the uri to redirect to after login. -* prompt - By default the login screen is displayed if the user is not logged-in to {{book.project.name}}. To only authenticate to the application if the user is already logged-in and not display the login page if the user is not logged-in, set this option to `none`. +* prompt - By default the login screen is displayed if the user is not logged-in to {{book.project.name}}. To only authenticate to the application if the user is already logged-in and not display the login page if the user is not logged-in, set this option to `none`. To always require re-authentication and ignore SSO, set this option to `login` . +* maxAge - Used just if user is already authenticated. Specifies maximum time since the authentication of user happened. If user is already authenticated for longer time than `maxAge`, the SSO is ignored and he will need to re-authenticate again. * loginHint - Used to pre-fill the username/email field on the login form. * action - If value is 'register' then user is redirected to registration page, otherwise to login page. * locale - Specifies the desired locale for the UI. @@ -264,10 +265,7 @@ Options is an Object, where: Returns the URL to login form on (options is an optional object with redirectUri and/or prompt fields). -Options is an Object, where: - -* redirectUri - Specifies the uri to redirect to after login. -* prompt - Can be set to 'none' to check if the user is logged in already (if not logged in, a login form is not displayed). +Options is an Object, which supports same options like the function `login` . ====== logout(options)