libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

Convert documentation to AsciiDoctor

Browse source
This commit is contained in:
Stian Thorgersen 2017-08-28 14:50:14 +02:00
parent 303bac6832
commit 44c6a3ca64
378 changed files with 2900 additions and 3963 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.force_build
View file

@ -1 +0,0 @@
Thu 16 Mar 08:18:49 CET 2017

9
OVERVIEW.adoc
View file

@ -1,9 +0,0 @@
= Keycloak Documentation
image:images/keycloak_logo.png[alt="Keycloak"]
{{book.project.name}} {{book.project.version}}
http://www.keycloak.org

36
README.md
View file

@ -9,7 +9,7 @@ For more information about Keycloak visit [Keycloak homepage](http://keycloak.or
Building Keycloak Documentation
-------------------------------
Ensure you have [GitBook installed](https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md)
Ensure you have [Maven installed](https://maven.apache.org/)
First clone the Keycloak Documentation repository:
@ -18,16 +18,9 @@ First clone the Keycloak Documentation repository:
To build Keycloak Documentation run:
gitbook build
mvn clean install build
You can then view the documentation by opening _book/index.html.
Alternatively you can also have the Gitbook tools continiously re-build when you do changes. To do this run:
gitbook serve
You can then view the documentation on http://localhost:4000.
You can then view the documentation by opening target/frames.html or target/index.html.
Building RH-SSO Documentation
@ -35,28 +28,11 @@ Building RH-SSO Documentation
Keycloak is the basis of [Red Hat Single Sign-On](https://access.redhat.com/products/red-hat-single-sign-on). The same documentation sources are used, but they are built slighty differently.
To build the documentation for RH-SSO go into the directory of the specific guide you want to build. For example to build Server Admin guide run:
To build the documentation for RH-SSO run:
cd server_admin
python ../gitlab-conversion.py
cd target
asciidoctor master.adoc
mvn clean install build -Dproduct
On Linux you can also run build-product.sh DIR. For example:
./build-product.sh server_admin
Or build all guides with:
./build-product.sh
If you have ccutil available you can build the guides with:
./build-product.sh -u
You can then view the documentation by opening server_admin/target/master.html
This will not create documentation that looks exactly as the official Red Hat Single Sign-On documentation, but the content will be the same.
You can then view the documentation by opening target/frames.html or target/index.html.
License

19
SUMMARY.adoc
View file

@ -1,19 +0,0 @@
= Keycloak Documentation
. link:getting_started/README.adoc[Getting Started]
{% include "./getting_started/SUMMARY.adoc" %}
. link:server_installation/README.adoc[Server Installation and Configuration]
{% include "./server_installation/SUMMARY.adoc" %}
. link:server_admin/README.adoc[Server Administration]
{% include "./server_admin/SUMMARY.adoc" %}
. link:securing_apps/README.adoc[Securing Applications and Services]
{% include "./securing_apps/SUMMARY.adoc" %}
. link:server_development/README.adoc[Server Development]
{% include "./server_development/SUMMARY.adoc" %}
. link:authorization_services/README.adoc[Authorization Services]
{% include "./authorization_services/SUMMARY.adoc" %}

179
aggregation/pom.xml Normal file
View file

@ -0,0 +1,179 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.keycloak.documentation</groupId>
<artifactId>documentation-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../</relativePath>
</parent>
<name>Aggregation</name>
<artifactId>aggregation</artifactId>
<packaging>pom</packaging>
<dependencies>
<dependency>
<groupId>org.keycloak.documentation</groupId>
<artifactId>authorization-services</artifactId>
<version>${project.version}</version>
<type>pom</type>
</dependency>
<dependency>
<groupId>org.keycloak.documentation</groupId>
<artifactId>getting-started</artifactId>
<version>${project.version}</version>
<type>pom</type>
</dependency>
<dependency>
<groupId>org.keycloak.documentation</groupId>
<artifactId>securing-apps</artifactId>
<version>${project.version}</version>
<type>pom</type>
</dependency>
<dependency>
<groupId>org.keycloak.documentation</groupId>
<artifactId>server-admin</artifactId>
<version>${project.version}</version>
<type>pom</type>
</dependency>
<dependency>
<groupId>org.keycloak.documentation</groupId>
<artifactId>server-development</artifactId>
<version>${project.version}</version>
<type>pom</type>
</dependency>
<dependency>
<groupId>org.keycloak.documentation</groupId>
<artifactId>server-installation</artifactId>
<version>${project.version}</version>
<type>pom</type>
</dependency>
</dependencies>
<build>
<outputDirectory>../target</outputDirectory>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-authorization_services</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/authorization_services/</outputDirectory>
<resources>
<resource>
<directory>../authorization_services/target/generated-docs</directory>
<include>**/**</include>
</resource>
</resources>
</configuration>
</execution>
<execution>
<id>copy-getting_started</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/getting_started/</outputDirectory>
<resources>
<resource>
<directory>../getting_started/target/generated-docs</directory>
<include>**/**</include>
</resource>
</resources>
</configuration>
</execution>
<execution>
<id>copy-securing_apps</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/securing_apps/</outputDirectory>
<resources>
<resource>
<directory>../securing_apps/target/generated-docs</directory>
<include>**/**</include>
</resource>
</resources>
</configuration>
</execution>
<execution>
<id>copy-server_admin</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/server_admin/</outputDirectory>
<resources>
<resource>
<directory>../server_admin/target/generated-docs</directory>
<include>**/**</include>
</resource>
</resources>
</configuration>
</execution>
<execution>
<id>copy-server_development</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/server_development/</outputDirectory>
<resources>
<resource>
<directory>../server_development/target/generated-docs</directory>
<include>**/**</include>
</resource>
</resources>
</configuration>
</execution>
<execution>
<id>copy-server_installation</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/server_installation/</outputDirectory>
<resources>
<resource>
<directory>../server_installation/target/generated-docs</directory>
<include>**/**</include>
</resource>
</resources>
</configuration>
</execution>
<execution>
<id>copy-index</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/</outputDirectory>
<resources>
<resource>
<directory>src</directory>
<include>*.*</include>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

17
aggregation/src/frames-index.html Normal file
View file

@ -0,0 +1,17 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Documentation Index</title>
</head>
<style>
img {
position: absolute;
top: 0; bottom:0; left: 0; right:0;
margin: auto;
}
</style>
<body>
<img src="keycloak_logo.png"/>
</body>
</html>

46
aggregation/src/frames-links.html Normal file
View file

@ -0,0 +1,46 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Documentation Index</title>
</head>
<style>
body {
background-color: #ededed;
font-family: sans-serif;
}
ul {
list-style-type: none;
margin: 0;
padding: 0;
overflow: hidden;
}
li {
float: left;
}
li a {
display: inline-block;
color: #004670;
text-align: center;
padding: 5px 16px;
text-decoration: none;
}
li a:hover {
color: #428bca;
}
</style>
<body>
<ul>
<li><a href="getting_started/${masterFile}.html" target="main">Getting Started</a></li>
<li><a href="server_installation/${masterFile}.html" target="main">Server Installation</a></li>
<li><a href="securing_apps/${masterFile}.html" target="main">Securing Apps</a></li>
<li><a href="server_admin/${masterFile}.html" target="main">Server Admin</a></li>
<li><a href="server_development/${masterFile}.html" target="main">Server Development</a></li>
<li><a href="authorization_services/${masterFile}.html" target="main">Authorization Services</a></li>
</ul>
</body>
</html>

11
aggregation/src/frames.html Normal file
View file

@ -0,0 +1,11 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Keycloak Documentation</title>
</head>
<frameset rows="45px,90%">
<frame name="top" src="frames-links.html" frameborder="0"/>
<frame name="main" src="frames-index.html" frameborder="0"/>
</frameset>
</html>

45
aggregation/src/index.html Normal file
View file

@ -0,0 +1,45 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Documentation Index</title>
</head>
<style>
body {
background-color: #ededed;
font-family: sans-serif;
}
ul {
list-style-type: none;
margin: 0;
padding: 0;
}
li {
padding: 5px;
}
li a {
color: #004670;
text-align: center;
padding: 5px 16px;
text-decoration: none;
}
li a:hover {
color: #428bca;
}
</style>
<body>
<img src="keycloak_logo.png"/>
<ul>
<li><a href="getting_started/${masterFile}.html">Getting Started</a></li>
<li><a href="server_installation/${masterFile}.html">Server Installation</a></li>
<li><a href="securing_apps/${masterFile}.html">Securing Apps</a></li>
<li><a href="server_admin/${masterFile}.html">Server Admin</a></li>
<li><a href="server_development/${masterFile}.html">Server Development</a></li>
<li><a href="authorization_services/${masterFile}.html">Authorization Services</a></li>
</ul>
</body>
</html>

0
images/keycloak_logo.png → aggregation/src/keycloak_logo.png Executable file → Normal file
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

14
assembly.xml Normal file
View file

@ -0,0 +1,14 @@
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
<id>asciidoc-html-zip</id>
<formats>
<format>zip</format>
</formats>
<fileSets>
<fileSet>
<directory>${project.build.directory}/generated-docs</directory>
<outputDirectory></outputDirectory>
</fileSet>
</fileSets>
</assembly>

8
authorization_services/README.adoc
View file

@ -1,8 +0,0 @@
= Authorization Services
image:images/keycloak_logo.png[alt="Keycloak"]
{{book.project.name}} {{book.project.version}}
http://www.keycloak.org

109
authorization_services/SUMMARY.adoc
View file

@ -1,109 +0,0 @@
= Authorization Services Guide
.. link:authorization_services/topics/overview/overview.adoc[Overview]
... link:authorization_services/topics/overview/architecture.adoc[Architecture]
... link:authorization_services/topics/overview/terminology.adoc[Terminology]
.. link:authorization_services/topics/getting-started/overview.adoc[Getting Started]
... link:authorization_services/topics/getting-started/hello-world/overview.adoc[Securing a Servlet Application]
.... link:authorization_services/topics/getting-started/hello-world/create-realm.adoc[Creating a Realm and a User]
.... link:authorization_services/topics/getting-started/hello-world/create-resource-server.adoc[Enabling Authorization Services]
.... link:authorization_services/topics/getting-started/hello-world/deploy.adoc[Build, Deploy, and Test Your Application]
{% if book.community %}
... link:authorization_services/topics/example/overview.adoc[Examples]
{% endif %}
.. link:authorization_services/topics/resource-server/overview.adoc[Managing Resource Servers]
... link:authorization_services/topics/resource-server/create-client.adoc[Creating a Client Application]
... link:authorization_services/topics/resource-server/enable-authorization.adoc[Enabling Authorization Services]
... link:authorization_services/topics/resource-server/default-config.adoc[Default Configuration]
... link:authorization_services/topics/resource-server/import-config.adoc[Export and Import Authorization Configuration]
.. link:authorization_services/topics/resource/overview.adoc[Managing Resources and Scopes]
... link:authorization_services/topics/resource/view.adoc[Viewing Resources]
... link:authorization_services/topics/resource/create.adoc[Creating Resources]
.. link:authorization_services/topics/policy/overview.adoc[Managing Policies]
... link:authorization_services/topics/policy/user-policy.adoc[User-Based Policy]
... link:authorization_services/topics/policy/role-policy.adoc[Role-Based Policy]
.... link:authorization_services/topics/policy/role-policy-required-role.adoc[Defining a Role as Required]
... link:authorization_services/topics/policy/js-policy.adoc[JavaScript-Based Policy]
... link:authorization_services/topics/policy/drools-policy.adoc[Rule-Based Policy]
... link:authorization_services/topics/policy/time-policy.adoc[Time-Based Policy]
... link:authorization_services/topics/policy/aggregated-policy.adoc[Aggregated Policy]
... link:authorization_services/topics/policy/client-policy.adoc[Client Policy]
... link:authorization_services/topics/policy/logic.adoc[Positive and Negative Logic]
... link:authorization_services/topics/policy/evaluation-api.adoc[Policy Evaluation API]
.. link:authorization_services/topics/permission/overview.adoc[Managing Permissions]
... link:authorization_services/topics/permission/create-resource.adoc[Creating Resource-Based Permissions]
.... link:authorization_services/topics/permission/typed-resource-permission.adoc[Typed Resource Permissions]
... link:authorization_services/topics/permission/create-scope.adoc[Creating Scope-Based Permissions]
... link:authorization_services/topics/permission/decision-strategy.adoc[Policy Decision Strategies]
.. link:authorization_services/topics/policy-evaluation-tool/overview.adoc[Evaluating and Testing Policies]
.. link:authorization_services/topics/service/overview.adoc[Authorization Services]
... link:authorization_services/topics/service/protection/protection-api.adoc[Protection API]
.... link:authorization_services/topics/service/protection/whatis-obtain-pat.adoc[What is a PAT and How to Obtain It]
.... link:authorization_services/topics/service/protection/resources-api-papi.adoc[Managing Resources]
.... link:authorization_services/topics/service/protection/permission-api-papi.adoc[Managing Permission Requests]
... link:authorization_services/topics/service/authorization/authorization-api.adoc[Authorization API]
.... link:authorization_services/topics/service/authorization/whatis-obtain-aat.adoc[What is an AAT and How to Obtain It]
.... link:authorization_services/topics/service/authorization/authorization-api-aapi.adoc[Requesting Authorization Data and Token]
... link:authorization_services/topics/service/entitlement/entitlement-api.adoc[Entitlement API]
.... link:authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc[Requesting Entitlements]
.... link:authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc[Entitlement Request Metadata]
... link:authorization_services/topics/service/rpt/overview.adoc[Requesting Party Token (RPT)]
.... link:authorization_services/topics/service/rpt/token-introspection.adoc[Introspecting a Requesting Party Token]
... link:authorization_services/topics/service/client-api.adoc[Authorization Client Java API]
.. link:authorization_services/topics/enforcer/overview.adoc[Policy Enforcers]
... link:authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc[{{book.project.name}} Adapter Policy Enforcer]
.... link:authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc[Protecting a Stateless Service Using a Bearer Token]
.... link:authorization_services/topics/enforcer/authorization-context.adoc[Obtaining the Authorization Context]
.... link:authorization_services/topics/enforcer/js-adapter.adoc[JavaScript Integration]
.... link:authorization_services/topics/enforcer/https.adoc[Setting up TLS/HTTPS]

54
authorization_services/book-product.json
View file

@ -1,54 +0,0 @@
{
"gitbook": "2.x.x",
"structure": {
"readme": "README.adoc"
},
"plugins": [
"toggle-chapters",
"ungrey",
"splitter"
],
"variables": {
"title": "Authorization Services Guide",
"community": false,
"product": true,
"images": "rhsso-images",
"appServer": "JBoss EAP 7",
"quickstartRepo": {
"name": "Quickstarts for the Red Hat Single Sign-On (SSO) Server",
"dir": "redhat-sso-quickstarts",
"link": "https://github.com/redhat-developer/redhat-sso-quickstarts"
},
"project": {
"name": "Red Hat Single Sign-On",
"version": "7.1.0",
"module": "Authorization Services",
"doc_base_url": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/",
"doc_info_version_url": "7.1"
},
"adapterguide": {
"name": "Securing Applications and Services Guide",
"link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/securing_applications_and_services_guide/"
},
"keycloakjsadapter": {
"name": "JavaScript OpenID Connect Adapter",
"link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/securing_applications_and_services_guide#javascript_adapter"
},
"gettingstarted": {
"name": "Getting Started",
"link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/getting_started_guide/"
},
"keycloakinstallingandboot": {
"name": "Installing and Boot",
"link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/getting_started_guide/#install-boot"
},
"keycloakinstallclientadapter": {
"name": "Installing the Client Adapter",
"link": "https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.1/html-single/getting_started_guide/#installing_the_client_adapter"
},
"subsystem": {
"undertow": "urn:jboss:domain:undertow:3.1"
}
}
}

80
authorization_services/buildGuide.sh
View file

@ -1,80 +0,0 @@
# Build the guide
# Find the directory name and full path
CURRENT_GUIDE=${PWD##*/}
CURRENT_DIRECTORY=$(pwd)
usage(){
cat <<EOM
USAGE: $0 [OPTION]
DESCRIPTION: Build the documentation in this directory.
OPTIONS:
-h Print help.
EOM
}
while getopts "ht:" c
do
case "$c" in
h) usage
exit 1;;
\?) echo "Unknown option: -$OPTARG." >&2
usage
exit 1;;
esac
done
echo ""
echo "********************************************"
echo " Building $CURRENT_GUIDE "
echo "********************************************"
if [ ! -d target ]; then
echo "You must run 'python gitlab-conversion.py' to convert the content before you run this script."
exit
fi
# Remove the guide directory path from the master.adoc file as it is not needed
echo ""
echo "***************************************************************************************"
echo "Removing the guide directory path from the master.adoc file as it is not needed."
echo "NOTE: The guide directory path should probably be removed from the SUMMARY.adoc file,"
echo "but since we do not know if it will break the upstream build, we are doing this here. "
echo "If it can not be removed from the SUMMARY.adoc file, this should really be done in the "
echo "Python script because otherwise you must run this script before porting content!"
echo "***************************************************************************************"
echo ""
find . -name 'master.adoc' -print | xargs sed -i "s/include::$CURRENT_GUIDE\//include::/g"
# Remove the html and build directories and then recreate the html/images/ directory
if [ -d target/html ]; then
rm -r target/html/
fi
if [ -d target/html ]; then
rm -r target/html/
fi
mkdir -p html
cp -r target/images/ target/html/
echo "Building an asciidoctor version of the guide"
asciidoctor -t -dbook -a toc -o target/html/$CURRENT_GUIDE.html target/master.adoc
echo ""
echo "Building a ccutil version of the guide"
ccutil compile --lang en_US --format html-single --main-file target/master.adoc
cd ..
echo "View the asciidoctor build here: " file://$CURRENT_DIRECTORY/target/html/$CURRENT_GUIDE.html
if [ -d $CURRENT_DIRECTORY/build/tmp/en-US/html-single/ ]; then
echo "View the ccutil build here: " file://$CURRENT_DIRECTORY/build/tmp/en-US/html-single/index.html
exit 0
else
echo -e "${RED}Build using ccutil failed!"
echo -e "${BLACK}See the log above for details."
exit 1
fi

113
authorization_services/gitlab-conversion.py
View file

@ -1,113 +0,0 @@
import sys, os, re, json, shutil, errno
def transform(root, f, targetdir):
full = os.path.join(root, f)
input = open(full, 'r').read()
dir = os.path.join(targetdir, root)
if not os.path.exists(dir):
os.makedirs(dir)
output = open(os.path.join(dir, f), 'w')
input = applyTransformation(input)
output.write(input)
def applyTransformation(input):
for variable in re.findall(r"\{\{(.*?)\}\}", input):
tmp = variable.replace('.', '_')
input = input.replace(variable, tmp)
input = input.replace('{{', '{').replace('}}', '}')
input = re.sub(r"<<fake.+#", "<<", input)
for variable in re.findall(r"[ ]*{% if (.*?) %}", input):
tmp = variable.replace('.', '_')
input = input.replace(variable, tmp)
exp = re.compile("[ ]*{% if (.*?) %}(.*?)[ ]*{% endif %}", re.DOTALL)
input = re.sub(exp, "ifeval::[{\g<1>}==true]\g<2>endif::[]", input)
input = re.sub(r"image:(\.\./)*", "image:", input)
input = re.sub(r"image::(\.\./)*", "image::", input)
return input
indir = 'topics'
targetdir = 'target'
if len(sys.argv) > 1:
targetdir = sys.argv[1]
if os.path.exists(targetdir):
shutil.rmtree(targetdir)
if os.path.isdir('images'):
shutil.copytree('images',os.path.join(targetdir, 'images'))
if os.path.isdir('keycloak-images'):
shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images'))
if os.path.isdir('rhsso-images'):
shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images'))
shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini'));
shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml'));
tmp = os.path.join(targetdir, 'topics')
if not os.path.exists(tmp):
os.makedirs(tmp)
# transform files
for root, dirs, filenames in os.walk(indir):
for f in filenames:
transform(root,f,targetdir)
# Create master.doc includes
input = open('SUMMARY.adoc', 'r').read()
output = open(os.path.join(targetdir, 'master.adoc'), 'w')
output.write("""
:toc:
:toclevels: 3
:numbered:
include::document-attributes.adoc[]
""")
input = re.sub(r"[ ]*\.+\s*link:[^/]+/(.*)\[(.*)\]", "include::\g<1>[]", input)
input = applyTransformation(input)
output.write(input)
# parse book-product.json file and create document attributes
with open('book-product.json') as data_file:
data = json.load(data_file)
variables = data['variables']
def makeAttributes(variables, variable, list):
for i in variables.keys():
if variable is None:
tmp = i
else:
tmp = variable + '_' + i
if isinstance(variables[i],dict):
makeAttributes(variables[i], tmp, list)
elif isinstance(variables[i],bool):
boolval = 'false'
if variables[i]:
boolval = 'true'
list.append({tmp: boolval})
else:
list.append({tmp: str(variables[i])})
attributeList = []
makeAttributes(variables, None, attributeList)
output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w')
for attribute in attributeList:
for k in attribute.keys():
output.write(':book_' + k + ": " + attribute[k] + "\n")
print "Transformation complete!"

6
authorization_services/index.adoc Normal file
View file

@ -0,0 +1,6 @@
:toc:
:toclevels: 3
:numbered:
include::../document-attributes-community.adoc[]
include::topics.adoc[]

10
authorization_services/master-docinfo.xml Executable file → Normal file
View file

@ -1,10 +1,10 @@
<productname>{book_project_name}</productname>
<productnumber>{book_project_doc_info_version_url}</productnumber>
<subtitle>For Use with {book_project_name} {book_project_doc_info_version_url}</subtitle>
<title>{book_title}</title>
<productname>{project_name}</productname>
<productnumber>{project_doc_info_version_url}</productnumber>
<subtitle>For Use with {project_name} {project_doc_info_version_url}</subtitle>
<title>{title}</title>
<release>{doc_info_version_url}</release>
<abstract>
<para>This guide consists of information for authorization services for {book_project_name} {book_project_doc_info_version_url}</para>
<para>This guide consists of information for authorization services for {project_name} {project_doc_info_version_url}</para>
</abstract>
<authorgroup>
<orgname>Red Hat Customer Content Services</orgname>

6
authorization_services/master.adoc Normal file
View file

@ -0,0 +1,6 @@
:toc:
:toclevels: 3
:numbered:
include::../document-attributes-product.adoc[]
include::topics.adoc[]

29
authorization_services/pom.xml Normal file
View file

@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.keycloak.documentation</groupId>
<artifactId>documentation-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../</relativePath>
</parent>
<name>Authorization Services</name>
<artifactId>authorization-services</artifactId>
<packaging>pom</packaging>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<executions>
<execution>
<id>asciidoc-to-html</id>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

106
authorization_services/topics.adoc Normal file
View file

@ -0,0 +1,106 @@
include::topics/overview/overview.adoc[]
include::topics/overview/architecture.adoc[]
include::topics/overview/terminology.adoc[]
include::topics/getting-started/overview.adoc[]
include::topics/getting-started/hello-world/overview.adoc[]
include::topics/getting-started/hello-world/create-realm.adoc[]
include::topics/getting-started/hello-world/create-resource-server.adoc[]
include::topics/getting-started/hello-world/deploy.adoc[]
ifeval::[{project_community}==true]
include::topics/example/overview.adoc[]
endif::[]
include::topics/resource-server/overview.adoc[]
include::topics/resource-server/create-client.adoc[]
include::topics/resource-server/enable-authorization.adoc[]
include::topics/resource-server/default-config.adoc[]
include::topics/resource-server/import-config.adoc[]
include::topics/resource/overview.adoc[]
include::topics/resource/view.adoc[]
include::topics/resource/create.adoc[]
include::topics/policy/overview.adoc[]
include::topics/policy/user-policy.adoc[]
include::topics/policy/role-policy.adoc[]
include::topics/policy/role-policy-required-role.adoc[]
include::topics/policy/js-policy.adoc[]
include::topics/policy/drools-policy.adoc[]
include::topics/policy/time-policy.adoc[]
include::topics/policy/aggregated-policy.adoc[]
include::topics/policy/client-policy.adoc[]
include::topics/policy/logic.adoc[]
include::topics/policy/evaluation-api.adoc[]
include::topics/permission/overview.adoc[]
include::topics/permission/create-resource.adoc[]
include::topics/permission/typed-resource-permission.adoc[]
include::topics/permission/create-scope.adoc[]
include::topics/permission/decision-strategy.adoc[]
include::topics/policy-evaluation-tool/overview.adoc[]
include::topics/service/overview.adoc[]
include::topics/service/protection/protection-api.adoc[]
include::topics/service/protection/whatis-obtain-pat.adoc[]
include::topics/service/protection/resources-api-papi.adoc[]
include::topics/service/protection/permission-api-papi.adoc[]
include::topics/service/authorization/authorization-api.adoc[]
include::topics/service/authorization/whatis-obtain-aat.adoc[]
include::topics/service/authorization/authorization-api-aapi.adoc[]
include::topics/service/entitlement/entitlement-api.adoc[]
include::topics/service/entitlement/entitlement-api-aapi.adoc[]
include::topics/service/entitlement/entitlement-request-metadata.adoc[]
include::topics/service/rpt/overview.adoc[]
include::topics/service/rpt/token-introspection.adoc[]
include::topics/service/client-api.adoc[]
include::topics/enforcer/overview.adoc[]
include::topics/enforcer/keycloak-enforcement-filter.adoc[]
include::topics/enforcer/keycloak-enforcement-bearer.adoc[]
include::topics/enforcer/authorization-context.adoc[]
include::topics/enforcer/js-adapter.adoc[]
include::topics/enforcer/https.adoc[]

10
authorization_services/topics/enforcer/authorization-context.adoc Executable file → Normal file
View file

@ -16,7 +16,7 @@ Obtaining the Authorization Context in a Servlet Container
[NOTE]
For more details about how you can obtain a `KeycloakSecurityContext` consult the adapter configuration. The example above should be sufficient
to obtain the context when running an application using any of the servlet containers supported by {{book.project.name}}.
to obtain the context when running an application using any of the servlet containers supported by {project_name}.
The authorization context helps give you more control over the decisions made and returned by the server. For example, you can use it
to build a dynamic menu where items are hidden or shown depending on the permissions associated with a resource or scope.
@ -35,7 +35,7 @@ if (authzContext.hasScopePermission("urn:project.com:project:create")) {
}
```
The `AuthorizationContext` represents one of the main capabilities of {{book.project.name}} {{book.project.module}}. From the examples above, you can see that the protected resource is not directly associated with the policies that govern them.
The `AuthorizationContext` represents one of the main capabilities of {project_name} Authorization Services. From the examples above, you can see that the protected resource is not directly associated with the policies that govern them.
Consider some similar code using role-based access control (RBAC):
@ -53,15 +53,15 @@ if (User.hasRole('project-manager')) {
}
```
Although both examples address the same requirements, they do so in different ways. In RBAC, roles only _implicitly_ define access for their resources. With {{book.project.name}} you gain the capability to create more manageable code that focuses directly on your resources whether you are using RBAC, attribute-based access control (ABAC), or any other BAC variant. Either you have the permission for a given resource or scope, or you don't.
Although both examples address the same requirements, they do so in different ways. In RBAC, roles only _implicitly_ define access for their resources. With {project_name} you gain the capability to create more manageable code that focuses directly on your resources whether you are using RBAC, attribute-based access control (ABAC), or any other BAC variant. Either you have the permission for a given resource or scope, or you don't.
Now, suppose your security requirements have changed and in addition to project managers, PMOs can also create new projects.
Security requirements change, but with {{book.project.name}} there is no need to change your application code to address the new requirements. Once your application is based on the resource and scope identifier, you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create` would be changed.
Security requirements change, but with {project_name} there is no need to change your application code to address the new requirements. Once your application is based on the resource and scope identifier, you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create` would be changed.
==== Using the AuthorizationContext to obtain an Authorization Client Instance
The ```AuthorizationContext``` can also be used to obtain a reference to the <<fake/../../service/client-api.adoc#_service_client_api, Authorization Client API>> configured to your application:
The ```AuthorizationContext``` can also be used to obtain a reference to the <<_service_client_api, Authorization Client API>> configured to your application:
```java
ClientAuthorizationContext clientContext = ClientAuthorizationContext.class.cast(authzContext);

4
authorization_services/topics/enforcer/https.adoc
View file

@ -12,8 +12,8 @@ When the server is using HTTPS, ensure your adapter is configured as follows:
```
The configuration above enables TLS/HTTPS to the Authorization Client, making possible to access a
{{book.project.name}} Server remotely using the HTTPS scheme.
{project_name} Server remotely using the HTTPS scheme.
[NOTE]
It is strongly recommended that you enable TLS/HTTPS when accessing the {{book.project.name}} Server endpoints.
It is strongly recommended that you enable TLS/HTTPS when accessing the {project_name} Server endpoints.

16
authorization_services/topics/enforcer/js-adapter.adoc Executable file → Normal file
View file

@ -1,10 +1,10 @@
[[_enforcer_js_adapter]]
==== JavaScript Integration
The {{book.project.name}} Server comes with a JavaScript library you can use to interact with a resource server protected by a policy enforcer.
This library is based on the {{book.project.name}} JavaScript adapter, which can be integrated to allow your client to obtain permissions from a {{book.project.name}} Server.
The {project_name} Server comes with a JavaScript library you can use to interact with a resource server protected by a policy enforcer.
This library is based on the {project_name} JavaScript adapter, which can be integrated to allow your client to obtain permissions from a {project_name} Server.
You can obtain this library from a running a {{book.project.name}} Server instance by including the following `script` tag in your web page:
You can obtain this library from a running a {project_name} Server instance by including the following `script` tag in your web page:
```html
<script src="http://.../auth/js/keycloak-authz.js"></script>
@ -17,18 +17,18 @@ var authorization = new KeycloakAuthorization(keycloak);
```
The *keycloak-authz.js* library provides two main features:
* Handle responses from a resource server protected by a <<fake/../overview.adoc#_enforcer_overview, {{book.project.name}} Policy Enforcer>> and obtain a requesting party token (RPT) with the necessary permissions to gain access to the protected resources on the resource server.
* Handle responses from a resource server protected by a <<_enforcer_overview, {project_name} Policy Enforcer>> and obtain a requesting party token (RPT) with the necessary permissions to gain access to the protected resources on the resource server.
** In this case, the library can handle whatever authorization protocol the resource server is using: <<fake/../../service/authorization/authorization-api.adoc#_service_authorization_api, UMA>> or <<fake/../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlements>>.
** In this case, the library can handle whatever authorization protocol the resource server is using: <<_service_entitlement_api, Entitlements>>.
* Obtain permissions from a {{book.project.name}} Server using the <<fake/../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement API>>.
* Obtain permissions from a {project_name} Server using the <<_service_entitlement_api, Entitlement API>>.
In both cases, the library allows you to easily interact with both resource server and {{book.project.name}} {{book.project.module}} to obtain tokens with
In both cases, the library allows you to easily interact with both resource server and {project_name} Authorization Services to obtain tokens with
permissions your client can use as bearer tokens to access the protected resources on a resource server.
===== Handling Authorization Responses from a Resource Server
If a resource server is protected by a policy enforcer, it responds to client requests based on the permissions carried along with a <<fake/../keycloak-enforcement-bearer.adoc#_enforcer_bearer, bearer token>>.
If a resource server is protected by a policy enforcer, it responds to client requests based on the permissions carried along with a <<_enforcer_bearer, bearer token>>.
Typically, when you try to access a resource server with a bearer token that is lacking permissions to access a protected resource, the resource server
responds with a *401* status code and a `WWW-Authenticate` header.

2
authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc Executable file → Normal file
View file

@ -41,6 +41,6 @@ HTTP/1.1 401 Unauthorized
WWW-Authenticate: KC_ETT realm="photoz-restful-api",as_uri="http://localhost:8080/auth/realms/photoz/authz/entitlement"
```
Once a client receives a response from the server, it examines the status code and `WWW-Authenticate` header to obtain an RPT from the {{book.project.name}} Server.
Once a client receives a response from the server, it examines the status code and `WWW-Authenticate` header to obtain an RPT from the {project_name} Server.

12
authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc
View file

@ -1,12 +1,12 @@
[[_enforcer_filter]]
=== {{book.project.name}} Adapter Policy Enforcer
=== {project_name} Adapter Policy Enforcer
You can enforce authorization decisions for your applications if you are using {{book.project.name}} OIDC adapters.
You can enforce authorization decisions for your applications if you are using {project_name} OIDC adapters.
When you enable policy enforcement for your {{book.project.name}} application, the corresponding adapter intercepts all requests to your application and enforces the authorization decisions obtained from the server.
When you enable policy enforcement for your {project_name} application, the corresponding adapter intercepts all requests to your application and enforces the authorization decisions obtained from the server.
Policy enforcement is strongly linked to your application's paths and the <<fake/../../resource/overview.adoc#_resource_overview, resources>> you created for a resource server using the {{book.project.name}} Administration Console. By default,
when you create a resource server, {{book.project.name}} creates a <<fake/../../resource-server/default-config.adoc#_resource_server_default_config, default configuration>> for your resource server so you can enable policy enforcement quickly.
Policy enforcement is strongly linked to your application's paths and the <<_resource_overview, resources>> you created for a resource server using the {project_name} Administration Console. By default,
when you create a resource server, {project_name} creates a <<_resource_server_default_config, default configuration>> for your resource server so you can enable policy enforcement quickly.
The default configuration allows access for all resources in your application provided the authenticated user belongs to the same realm as the resource server being protected.
@ -68,7 +68,7 @@ Here is a description of each configuration option:
* *policy-enforcer*
+
Specifies the configuration options that define how policies are actually enforced and optionally the paths you want to protect. If not specified, the policy enforcer queries the server
for all resources associated with the resource server being protected. In this case, you need to ensure the resources are properly configured with a <<fake/../../resource/create.adoc#_resource_create_uri, URI>> property that matches the paths you want to protect.
for all resources associated with the resource server being protected. In this case, you need to ensure the resources are properly configured with a <<_resource_create_uri, URI>> property that matches the paths you want to protect.
+
** *user-managed-access*
+

6
authorization_services/topics/enforcer/overview.adoc Executable file → Normal file
View file

@ -1,8 +1,8 @@
[[_enforcer_overview]]
== Policy Enforcers
Policy Enforcement Point (PEP) is a design pattern and as such you can implement it in different ways. {{book.project.name}} provides all the necessary means
to implement PEPs for different platforms, environments, and programming languages. {{book.project.name}} {{book.project.module}} presents a RESTful API,
Policy Enforcement Point (PEP) is a design pattern and as such you can implement it in different ways. {project_name} provides all the necessary means
to implement PEPs for different platforms, environments, and programming languages. {project_name} Authorization Services presents a RESTful API,
and leverages OAuth2 authorization capabilities for fine-grained authorization using a centralized authorization server.
image:../../images/pep-pattern-diagram.png[alt="PEP Overview"]
image:images/pep-pattern-diagram.png[alt="PEP Overview"]

14
authorization_services/topics/example/overview.adoc Executable file → Normal file
View file

@ -1,12 +1,12 @@
[[_example_overview]]
== Examples
The {{book.project.name}} Authorization can also help you to quickly get started with the authorization services and understand how to apply the same concepts to your
The {project_name} Authorization can also help you to quickly get started with the authorization services and understand how to apply the same concepts to your
own applications.
If you are using the {{book.project.name}} Demo Distribution and you have it properly extracted in your file system:
If you are using the {project_name} Demo Distribution and you have it properly extracted in your file system:
* **keycloak-demo-{{book.project.version}}.[zip|tar.gz]**
* **keycloak-demo-{project_version}.[zip|tar.gz]**
you can check out the available examples from the following directory:
@ -14,7 +14,7 @@ you can check out the available examples from the following directory:
cd ${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz
```
Or you can get them from https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz[GitHub].
Or you can get them from https://github.com/keycloak/keycloak/tree/{project_version}/examples/authz[GitHub].
Each example has a `README` file with instructions about how to build, deploy, and test the example.
@ -24,12 +24,12 @@ Here is a brief description of each example:
|===
|Name |Description
| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/hello-world-authz-service[hello-world-authz-service]
| https://github.com/keycloak/keycloak/tree/{project_version}/examples/authz/hello-world-authz-service[hello-world-authz-service]
| A single-page application that is protected by a policy enforcer that decides whether a user can access that page based on the permissions obtained from a Keycloak Server.
| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/photoz[photoz]
| https://github.com/keycloak/keycloak/tree/{project_version}/examples/authz/photoz[photoz]
| A simple application based on HTML5+AngularJS+JAX-RS that demonstrates how to enable fine-grained permissions to RESTFul based services and HTML5 clients.
| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/servlet-authz[servlet-authz]
| https://github.com/keycloak/keycloak/tree/{project_version}/examples/authz/servlet-authz[servlet-authz]
| A simple Servlet-based application that demonstrates how to enable fine-grained authorization to a JBoss/Wildfly Servlet Application.
|===

10
authorization_services/topics/getting-started/hello-world/before-start.adoc
View file

@ -1,15 +1,15 @@
=== Before You Start
This guide is based on the *{{book.project.name}} Demo Distribution*. Download the demo distribution before proceeding.
This guide is based on the *{project_name} Demo Distribution*. Download the demo distribution before proceeding.
[NOTE]
This guide assumes that you are already familiar with {{book.project.name}} and that you are able to install and boot a {{book.project.name}} Server. For more information, see https://keycloak.gitbooks.io/getting-started-tutorials/content/[the Getting Started tutorials].
This guide assumes that you are already familiar with {project_name} and that you are able to install and boot a {project_name} Server. For more information, see https://keycloak.gitbooks.io/getting-started-tutorials/content/[the Getting Started tutorials].
Ensure you have a {{book.project.name}} instance running; the default configuration is http://localhost:8080/auth[http://localhost:8080/auth]. After logging in to the
Ensure you have a {project_name} instance running; the default configuration is http://localhost:8080/auth[http://localhost:8080/auth]. After logging in to the
Administration Console, a page similar to this one is displayed:
.{{book.project.name}} Administration Console
image:../../{{book.images}}/getting-started/kc-start-page.png[alt="{{book.project.name}} Administration Console"]
.{project_name} Administration Console
image:{project_images}/getting-started/kc-start-page.png[alt="{project_name} Administration Console"]
The source code for the getting started tutorials can be obtained from the demo distributions. The authorization-related examples
are located at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz*.

8
authorization_services/topics/getting-started/hello-world/create-realm.adoc
View file

@ -5,14 +5,14 @@ The first step is to create a realm and a user in that realm. The realm consists
* A single user
* A single client application, which then becomes a <<fake/../../../overview/terminology.adoc#_overview_terminology, resource server>> for which you need to enable authorization services.
* A single client application, which then becomes a <<_overview_terminology, resource server>> for which you need to enable authorization services.
To create a realm and a user complete the following steps:
. Create a realm with a name *hello-world-authz*. Once created, a page similar to the following is displayed:
+
.Realm hello-world-authz
image:../../../{{book.images}}/getting-started/hello-world/create-realm.png[alt="Realm hello-world-authz"]
image:{project_images}/getting-started/hello-world/create-realm.png[alt="Realm hello-world-authz"]
. Create a user for your newly created realm. Click *Users*. The user list page opens.
@ -22,12 +22,12 @@ image:../../../{{book.images}}/getting-started/hello-world/create-realm.png[alt=
Click the *User Enabled* switch to *On*, and then click *Save*.
+
.Add User
image:../../../{{book.images}}/getting-started/hello-world/create-user.png[alt="Add User"]
image:{project_images}/getting-started/hello-world/create-user.png[alt="Add User"]
. Set a password for the user by clicking the *Credentials* tab.
+
.Set User Password
image:../../../{{book.images}}/getting-started/hello-world/reset-user-pwd.png[alt="Set User Password"]
image:{project_images}/getting-started/hello-world/reset-user-pwd.png[alt="Set User Password"]
. Complete the *New Password* and *Password Confirmation* fields with a password and click the *Temporary* switch to *OFF*.

10
authorization_services/topics/getting-started/hello-world/create-resource-server.adoc
View file

@ -8,12 +8,12 @@ To create a new client, complete the following steps:
. Click *Clients* to start creating a new client application and fill in the *Client ID*, *Client Protocol*, and *Root URL* fields.
+
.Create Client Application
image:../../../{{book.images}}/getting-started/hello-world/create-client.png[alt="Create Client Application"]
image:{project_images}/getting-started/hello-world/create-client.png[alt="Create Client Application"]
. Click *Save*. The Client Details page is displayed.
+
.Client Details
image:../../../{{book.images}}/getting-started/hello-world/enable-authz.png[alt="Client Details"]
image:{project_images}/getting-started/hello-world/enable-authz.png[alt="Client Details"]
. On the Client Details page, click the *Authorization Enabled* switch to *ON*, and then click *Save*.
A new *Authorization* tab is displayed for the client.
@ -21,8 +21,8 @@ A new *Authorization* tab is displayed for the client.
. Click the *Authorization* tab and an Authorization Settings page similar to the following is displayed:
+
.Authorization Settings
image:../../../{{book.images}}/getting-started/hello-world/authz-settings.png[alt="Authorization Settings"]
image:{project_images}/getting-started/hello-world/authz-settings.png[alt="Authorization Settings"]
When you enable authorization services for a client application, {{book.project.name}} automatically creates several <<fake/../../../resource-server/default-config.adoc#_resource_server_default_config, default settings>> for your client authorization configuration.
When you enable authorization services for a client application, {project_name} automatically creates several <<_resource_server_default_config, default settings>> for your client authorization configuration.
For more information about authorization configuration, see <<fake/../../../resource-server/enable-authorization.adoc#_resource_server_enable_authorization, Enabling Authorization Services>>.
For more information about authorization configuration, see <<_resource_server_enable_authorization, Enabling Authorization Services>>.

30
authorization_services/topics/getting-started/hello-world/deploy.adoc
View file

@ -3,43 +3,43 @@
Now that the *app-authz-vanilla* resource server (or client) is properly configured and authorization services are enabled, it can be deployed to the server.
The project and code for the application you are going to deploy is available in link:{{book.quickstartRepo.link}}[{{book.quickstartRepo.name}}]. You will need the following
The project and code for the application you are going to deploy is available in link:{quickstartRepo_link}[{quickstartRepo_name}]. You will need the following
installed on your machine and available in your PATH before you can continue:
* Java JDK 8
* Apache Maven 3.1.1 or higher
* Git
You can obtain the code by cloning the repository at {{book.quickstartRepo.link}}. The default branch corresponds to the latest release of {{book.project.name}}. Follow these steps to download the code.
You can obtain the code by cloning the repository at {quickstartRepo_link}. The default branch corresponds to the latest release of {project_name}. Follow these steps to download the code.
.Clone Project
[source, subs="attributes"]
----
$ git clone {{book.quickstartRepo.link}}
$ git clone {quickstartRepo_link}
----
The application we are about to build and deploy is located at
[source, subs="attributes"]
----
$ cd {{book.quickstartRepo.dir}}/app-authz-jee-vanilla
$ cd {quickstartRepo_dir}/app-authz-jee-vanilla
----
==== Obtaining the Adapter Configuration
You must first obtain the adapter configuration before building and deploying the application.
To obtain the adapter configuration from the {{book.project.name}} Administration Console, complete the following steps.
To obtain the adapter configuration from the {project_name} Administration Console, complete the following steps.
. Click *Clients*. In the client listing, click the *app-authz-vanilla* client application. The Client Details page opens.
+
.Client Details
image:../../../{{book.images}}/getting-started/hello-world/enable-authz.png[alt="Client Details"]
image:{project_images}/getting-started/hello-world/enable-authz.png[alt="Client Details"]
. Click the *Installation* tab. From the Format Option dropdown list, select *Keycloak OIDC JSON*. The adapter configuration is displayed in JSON format. Click *Download*.
+
.Adapter Configuration
image:../../../{{book.images}}/getting-started/hello-world/adapter-config.png[alt="Adapter Configuration"]
image:{project_images}/getting-started/hello-world/adapter-config.png[alt="Adapter Configuration"]
. Move the file `keycloak.json` to the `app-authz-jee-vanilla/config` directory.
@ -64,21 +64,21 @@ $ mvn clean package wildfly:deploy
==== Testing the Application
If your application was successfully deployed you can access it at http://localhost:8080/app-authz-vanilla[http://localhost:8080/app-authz-vanilla]. The {{book.project.name}} Login page opens.
If your application was successfully deployed you can access it at http://localhost:8080/app-authz-vanilla[http://localhost:8080/app-authz-vanilla]. The {project_name} Login page opens.
.Login Page
image:../../../{{book.images}}/getting-started/hello-world/login-page.png[alt="Login Page"]
image:{project_images}/getting-started/hello-world/login-page.png[alt="Login Page"]
Log in as *alice* using the password you specified for that user. After authenticating, the following page is displayed:
.Hello World Authz Main Page
image:../../../{{book.images}}/getting-started/hello-world/main-page.png[alt="Hello World Authz Main Page"]
image:{project_images}/getting-started/hello-world/main-page.png[alt="Hello World Authz Main Page"]
The <<fake/../../../resource-server/default-config.adoc#_resource_server_default_config, default settings>> defined by {{book.project.name}} when you enable authorization services for a client application provide a simple
The <<_resource_server_default_config, default settings>> defined by {project_name} when you enable authorization services for a client application provide a simple
policy that always grants access to the resources protected by this policy.
You can start by changing the default permissions and policies and test how your application responds, or even create new policies using the different
<<fake/../../../policy/overview.adoc#_policy_overview, policy types>> provided by {{book.project.name}}.
<<_policy_overview, policy types>> provided by {project_name}.
There are a plenty of things you can do now to test this application. For example, you can change the default policy by clicking the Authorization tab for the client, then `Policies` tab, then click on `Default Policy` in the list to allow you to change it as follows:
@ -91,7 +91,7 @@ $evaluation.deny();
Now, log out of the demo application and log in again. You can no longer access the application.
image:../../../{{book.images}}/getting-started/hello-world/access-denied-page.png[alt="Access Denied Page"]
image:{project_images}/getting-started/hello-world/access-denied-page.png[alt="Access Denied Page"]
Let's fix that now, but instead of changing the `Default Policy` code we are going to change the `Logic` to `Negative` using the dropdown list below the policy code text area.
That re-enables access to the application as we are negating the result of that policy, which is by default denying all requests for access. Again, before testing this change, be sure to log out and log in again.
@ -101,6 +101,6 @@ That re-enables access to the application as we are negating the result of that
There are additional things you can do, such as:
* Create a scope, define a policy and permission for it, and test it on the application side. Can the user perform an action (or anything else represented by the scope you created)?
* Create different types of policies such as <<fake/../../../policy/role-policy.adoc#_policy_rbac, role-based>>, <<fake/../../../policy/user-policy.adoc#_policy_user, user-based>>, <<fake/../../../policy/time-policy.adoc#_policy_time, time-based>>, <<fake/../../../policy/aggregated-policy.adoc#_policy_aggregated, aggregated policies>>, or <<fake/../../../policy/drools-policy.adoc#_policy_drools, rule-based>>, and associate these policies with the `Default Permission`.
* Create different types of policies such as <<_policy_drools, rule-based>>, and associate these policies with the `Default Permission`.
* Apply multiple policies to the `Default Permission` and test the behavior. For example, combine multiple policies and change the `Decision Strategy` accordingly.
* For more information about how to view and test permissions inside your application see <<fake/../../../enforcer/authorization-context.adoc#_enforcer_authorization_context, Obtaining the Authorization Context>>.
* For more information about how to view and test permissions inside your application see <<_enforcer_authorization_context, Obtaining the Authorization Context>>.

4
authorization_services/topics/getting-started/hello-world/overview.adoc
View file

@ -1,11 +1,11 @@
[[_getting_started_hello_world_overview]]
=== Securing a Servlet Application
The purpose of this getting started guide is to get you up and running as quickly as possible so that you can experiment with and test various authorization features provided by {{book.project.name}}.
The purpose of this getting started guide is to get you up and running as quickly as possible so that you can experiment with and test various authorization features provided by {project_name}.
This quick tour relies heavily on the default database and server configurations and does not cover complex deployment options.
For more information on features or configuration options, see the appropriate sections in this documentation.
This guide explains key concepts about {{book.project.name}} {{book.project.module}}:
This guide explains key concepts about {project_name} Authorization Services:
* Enabling fine-grained authorization for a client application
* Configuring a client application to be a resource server, with protected resources

10
authorization_services/topics/getting-started/overview.adoc
View file

@ -1,10 +1,10 @@
[[_getting_started_overview]]
== Getting Started
Before you can use this tutorial, you need to complete the installation of {{book.project.name}} and create the initial admin user as shown in the link:{{book.gettingstarted.link}}[{{book.gettingstarted.name}}] tutorial.
There is one caveat to this. You have to run a separate {{book.appServer}} instance on the same machine as {{book.project.name}} Server. This separate instance will run your Java Servlet application. Because of this you will have to run the {{book.project.name}} under a different port so that there are no port conflicts when running on the same machine. Use the `jboss.socket.binding.port-offset` system property on the command line. The value of this property is a number that will be added to the base value of every port opened by {{book.project.name}} Server.
Before you can use this tutorial, you need to complete the installation of {project_name} and create the initial admin user as shown in the link:{gettingstarted_link}[{gettingstarted_name}] tutorial.
There is one caveat to this. You have to run a separate {appServer} instance on the same machine as {project_name} Server. This separate instance will run your Java Servlet application. Because of this you will have to run the {project_name} under a different port so that there are no port conflicts when running on the same machine. Use the `jboss.socket.binding.port-offset` system property on the command line. The value of this property is a number that will be added to the base value of every port opened by {project_name} Server.
To boot {{book.project.name}} Server:
To boot {project_name} Server:
.Linux/Unix
[source]
@ -18,7 +18,7 @@ $ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100
> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100
----
For more details about how to install and configure a {{book.appServer}}, please follow the steps on the link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] tutorial.
For more details about how to install and configure a {appServer}, please follow the steps on the link:{adapterguide_link}[{adapterguide_name}] tutorial.
After installing and booting both servers you should be able to access {{book.project.name}} Admin Console at http://localhost:8180/auth/admin/ and also the {{book.appServer}} instance at
After installing and booting both servers you should be able to access {project_name} Admin Console at http://localhost:8180/auth/admin/ and also the {appServer} instance at
http://localhost:8080.

48
authorization_services/topics/overview/architecture.adoc Executable file → Normal file
View file

@ -1,35 +1,35 @@
[[_overview_architecture]]
=== Architecture
image:../../images/authz-arch-overview.png[alt="{{book.project.name}} AuthZ Architecture Overview"]
image:images/authz-arch-overview.png[alt="{project_name} AuthZ Architecture Overview"]
From a design perspective, {{book.project.module}} is based on a well-defined set of authorization patterns providing these capabilities:
From a design perspective, Authorization Services is based on a well-defined set of authorization patterns providing these capabilities:
* **Policy Administration Point (PAP)**
+
Provides a set of UIs based on the {{book.project.name}} Administration Console to manage resource servers, resources, scopes, permissions, and policies.
Part of this is also accomplished remotely through the use of the <<fake/../../service/protection/protection-api.adoc#_service_protection_api, Protection API>>.
Provides a set of UIs based on the {project_name} Administration Console to manage resource servers, resources, scopes, permissions, and policies.
Part of this is also accomplished remotely through the use of the <<_service_protection_api, Protection API>>.
+
* **Policy Decision Point (PDP)**
+
Provides a distributable policy decision point to where authorization requests are sent and policies are evaluated accordingly with the permissions being requested. Part of this is also accomplished remotely through the use of the
<<fake/../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization>> and <<fake/../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement>> APIs.
<<_service_entitlement_api, Entitlement>> APIs.
+
* **Policy Enforcement Point (PEP)**
+
Provides implementations for different environments to actually enforce authorization decisions at the resource server side.
{{book.project.name}} provides some built-in <<fake/../../enforcer/overview.adoc#_enforcer_overview, Policy Enforcers>>.
{project_name} provides some built-in <<_enforcer_overview, Policy Enforcers>>.
+
* **Policy Information Point (PIP)**
+
Being based on {{book.project.name}} Authentication Server, you can obtain attributes from identities and runtime environment during the evaluation of authorization policies.
Being based on {project_name} Authentication Server, you can obtain attributes from identities and runtime environment during the evaluation of authorization policies.
==== The Authorization Process
Three main processes define the necessary steps to understand how to use {{book.project.name}} to enable fine-grained authorization to your applications:
Three main processes define the necessary steps to understand how to use {project_name} to enable fine-grained authorization to your applications:
* *Resource Management*
* *Permission and Policy Management*
@ -39,19 +39,19 @@ Three main processes define the necessary steps to understand how to use {{book.
*Resource Management* involves all the necessary steps to define what is being protected.
image:../../images/resource-mgmt-process.png[alt="Resource Management Overview"]
image:images/resource-mgmt-process.png[alt="Resource Management Overview"]
First, you need to specify {{book.project.name}} what are you looking to protect, which usually represents a web application or a set of one or more services. For more information on resource servers see <<fake/../../overview/terminology.adoc#_overview_terminology, Terminology>>.
First, you need to specify {project_name} what are you looking to protect, which usually represents a web application or a set of one or more services. For more information on resource servers see <<_overview_terminology, Terminology>>.
Resource servers are managed using the {{book.project.name}} Administration Console. There you can enable any registered client application as a resource server and start managing the resources and scopes you want to protect.
Resource servers are managed using the {project_name} Administration Console. There you can enable any registered client application as a resource server and start managing the resources and scopes you want to protect.
image:../../images/rs-r-scopes.png[alt="Resource Server Overview"]
image:images/rs-r-scopes.png[alt="Resource Server Overview"]
A resource can be a web page, a RESTFul resource, a file in your file system, an EJB, and so on. They can represent a group of resources (just like a Class in Java) or they can represent a single and specific resource.
For instance, you might have a _Bank Account_ resource that represents all banking accounts and use it to define the authorization policies that are common to all banking accounts. However, you might want to define specific policies for _Alice Account_ (a resource instance that belongs to a customer), where only the owner is allowed to access some information or perform an operation.
Resources can be managed using the {{book.project.name}} Administration Console or the <<fake/../../service/protection/protection-api.adoc#_service_protection_api, Protection API>>. In the latter case, resource servers are able to manage their resources remotely.
Resources can be managed using the {project_name} Administration Console or the <<_service_protection_api, Protection API>>. In the latter case, resource servers are able to manage their resources remotely.
Scopes usually represent the actions that can be performed on a resource, but they are not limited to that. You can also use scopes to represent one or more attributes within a resource.
@ -61,13 +61,13 @@ Once you have defined your resource server and all the resources you want to pro
This process involves all the necessary steps to actually define the security and access requirements that govern your resources.
image:../../images/policy-mgmt-process.png[alt="Permission and Policy Management Overview"]
image:images/policy-mgmt-process.png[alt="Permission and Policy Management Overview"]
Policies define the conditions that must be satisfied to access or perform operations on something (resource or scope), but they are not tied to what they are protecting. They are generic and can be reused to build permissions or even more complex policies.
For instance,to allow access to a group of resources only for users granted with a role "User Premium,"" you can use RBAC (Role-based Access Control).
{{book.project.name}} provides a few built-in policy types (and their respective policy providers) covering the most common access control mechanisms. You can even create policies based on rules written using JavaScript or JBoss Drools.
{project_name} provides a few built-in policy types (and their respective policy providers) covering the most common access control mechanisms. You can even create policies based on rules written using JavaScript or JBoss Drools.
Once you have your policies defined, you can start defining your permissions. Permissions are coupled with the resource they are protecting. Here you specify
what you want to protect (resource or scope) and the policies that must be satisfied to grant or deny permission.
@ -76,9 +76,9 @@ what you want to protect (resource or scope) and the policies that must be satis
*Policy Enforcement* involves the necessary steps to actually enforce authorization decisions to a resource server. This is achieved by enabling a *Policy Enforcement Point* or PEP at the resource server that is capable of communicating with the authorization server, ask for authorization data and control access to protected resources based on the decisions and permissions returned by the server.
image:../../images/pep-pattern-diagram.png[alt="PEP Overview"]
image:images/pep-pattern-diagram.png[alt="PEP Overview"]
{{book.project.name}} provides some built-in <<fake/../../enforcer/overview.adoc#_enforcer_overview, Policy Enforcers>> implementations that you can use to protect your applications depending on the platform they are running on.
{project_name} provides some built-in <<_enforcer_overview, Policy Enforcers>> implementations that you can use to protect your applications depending on the platform they are running on.
==== Authorization Services
@ -109,24 +109,24 @@ The operations provided by the Protection API can be organized in two main group
** Issue Permission Tickets
[NOTE]
By default, Remote Resource Management is enabled. You can change that using the {{book.project.name}} Administration Console and only allow resource management through the console.
By default, Remote Resource Management is enabled. You can change that using the {project_name} Administration Console and only allow resource management through the console.
When using the UMA protocol, the issuance of Permission Tickets by the Protection API is an important part of the whole authorization process. As described in a subsequent section, they represent the permissions being requested by the client and that are sent to the server to obtain a final token with all permissions granted during the evaluation of the permissions and policies associated with the resources and scopes being requested.
For more information, see <<fake/../../service/protection/protection-api.adoc#_service_protection_api, Protection API>>.
For more information, see <<_service_protection_api, Protection API>>.
===== Authorization API
The Authorization API is also a https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA-compliant] endpoint providing a single operation that exchanges an Access Token and <<fake/.././terminology.adoc#_overview_terminology_permission_ticket, Permission Ticket>> with a Requesting Party Token (RPT).
The Authorization API is also a https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA-compliant] endpoint providing a single operation that exchanges an Access Token and <<_overview_terminology_permission_ticket, Permission Ticket>> with a Requesting Party Token (RPT).
The RPT contains all permissions granted to a client and can be used to call a resource server to get access to its protected resources.
When requesting an RPT you can also provide a previously issued RPT. In this case, the resulting RPT will consist of the union of the permissions from the previous RPT and the new ones
within a permission ticket.
image:../../images/authz-calls.png[alt="Authorization API Overview"]
image:images/authz-calls.png[alt="Authorization API Overview"]
For more information, see <<fake/../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization API>>.
For more information, see <<_service_authorization_api, Authorization API>>.
==== Entitlement API
@ -135,9 +135,9 @@ The Entitlement API provides a 1-legged protocol to issue RPTs. Unlike the Autho
From this API you can obtain all the entitlements or permissions for a user (based on the resources managed by a given resource server) or just the entitlements for a set of
one or more resources.
image:../../images/entitlement-calls.png[alt="Entitlement API Overview"]
image:images/entitlement-calls.png[alt="Entitlement API Overview"]
For more information see <<fake/../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement API>>.
For more information see <<_service_entitlement_api, Entitlement API>>.

14
authorization_services/topics/overview/overview.adoc Executable file → Normal file
View file

@ -1,14 +1,14 @@
[[_overview]]
== Overview
{% if book.product %}
NOTE: {{book.project.module}} is a Technology Preview feature and is not fully supported. This feature is disabled by default.
ifeval::[{project_product}==true]
NOTE: Authorization Services is a Technology Preview feature and is not fully supported. This feature is disabled by default.
To enable {{book.project.module}} add the `standalone/configuration/profile.properties` file with the contents `profile=preview`
To enable Authorization Services add the `standalone/configuration/profile.properties` file with the contents `profile=preview`
or start the server with `-Dkeycloak.profile=preview` to enable all technology preview features.
{% endif %}
endif::[]
{{book.project.name}} supports fine-grained authorization policies and is able to combine different access control
{project_name} supports fine-grained authorization policies and is able to combine different access control
mechanisms such as:
* **Attribute-based access control (ABAC)**
@ -21,7 +21,7 @@ mechanisms such as:
* **Time-based access control**
* **Support for custom access control mechanisms (ACMs) through a Policy Provider Service Provider Interface (SPI)**
{{book.project.name}} is based on a set of administrative UIs and a RESTful API, and provides the necessary means to create permissions
{project_name} is based on a set of administrative UIs and a RESTful API, and provides the necessary means to create permissions
for your protected resources and scopes, associate those permissions with authorization policies, and enforce authorization decisions in your applications and services.
Resource servers (applications or services serving protected resources) usually rely on some kind of information to decide if access should be granted to a protected resource. For RESTful-based resource servers, that information is usually obtained from a security token, usually sent as a bearer token on every request to the server. For web applications that rely on a session to authenticate users, that information is usually stored in a user's session and retrieved from there for each request.
@ -34,7 +34,7 @@ Frequently, resource servers only perform authorization decisions based on role-
* It is not the most flexible access control mechanism. Roles do not represent who you are and lack contextual information. If you have been granted a role, you have at least some access.
Considering that today we need to consider heterogeneous environments where users are distributed across different regions, with different local policies,
using different devices, and with a high demand for information sharing, {{book.project.name}} Authorization Services can help you improve the authorization capabilities of your applications and services by providing:
using different devices, and with a high demand for information sharing, {project_name} Authorization Services can help you improve the authorization capabilities of your applications and services by providing:
* Resource protection using fine-grained authorization policies and different access control mechanisms
* Centralized Resource, Permission, and Policy Management

16
authorization_services/topics/overview/terminology.adoc Executable file → Normal file
View file

@ -1,7 +1,7 @@
[[_overview_terminology]]
=== Terminology
Before going further, it is important to understand these terms and concepts introduced by {{book.project.name}} {{book.project.module}}.
Before going further, it is important to understand these terms and concepts introduced by {project_name} Authorization Services.
[[_overview_terminology_resource_server]]
==== Resource Server
@ -12,7 +12,7 @@ Resource servers usually rely on some kind of information to decide whether acce
that information is usually carried in a security token, typically sent as a bearer token along with every request to the server. Web applications that rely on a session to
authenticate users usually store that information in the user's session and retrieve it from there for each request.
In {{book.project.name}}, any *confidential* client application can act as a resource server. This client's resources and their respective scopes are protected and governed by a set of authorization policies.
In {project_name}, any *confidential* client application can act as a resource server. This client's resources and their respective scopes are protected and governed by a set of authorization policies.
==== Resource
@ -39,7 +39,7 @@ A permission associates the object being protected with the policies that must b
*** *Y* represents an action to be performed, for example, write, view, and so on.
*** *Z* represents a protected resource, for example, "/accounts".
{{book.project.name}} provides a rich platform for building a range of permission strategies ranging from simple to very complex, rule-based dynamic permissions. It provides flexibility and helps to:
{project_name} provides a rich platform for building a range of permission strategies ranging from simple to very complex, rule-based dynamic permissions. It provides flexibility and helps to:
* Reduce code refactoring and permission management costs
* Support a more flexible security model, helping you to easily adapt to changes in your security requirements
@ -52,16 +52,16 @@ but rather the conditions that must be satisfied for access to a given object (f
Policies are strongly related to the different access control mechanisms (ACMs) that you can use to protect your resources.
With policies, you can implement strategies for attribute-based access control (ABAC), role-based access control (RBAC), context-based access control, or any combination of these.
{{book.project.name}} leverages the concept of policies and how you define them by providing the concept of aggregated policies, where you can build a "policy of policies" and still control the behavior of the evaluation.
Instead of writing one large policy with all the conditions that must be satisfied for access to a given resource, the policies implementation in {{book.project.name}} {{book.project.module}} follows the divide-and-conquer technique.
{project_name} leverages the concept of policies and how you define them by providing the concept of aggregated policies, where you can build a "policy of policies" and still control the behavior of the evaluation.
Instead of writing one large policy with all the conditions that must be satisfied for access to a given resource, the policies implementation in {project_name} Authorization Services follows the divide-and-conquer technique.
That is, you can create individual policies, then reuse them with different permissions and build more complex policies by combining individual policies.
==== Policy Provider
Policy providers are implementations of specific policy types. {{book.project.name}} provides built-in policies, backed by their corresponding
Policy providers are implementations of specific policy types. {project_name} provides built-in policies, backed by their corresponding
policy providers, and you can create your own policy types to support your specific requirements.
{{book.project.name}} provides a SPI (Service Provider Interface) that you can use to plug in your own policy provider implementations.
{project_name} provides a SPI (Service Provider Interface) that you can use to plug in your own policy provider implementations.
[[_overview_terminology_permission_ticket]]
==== Permission Ticket
@ -73,4 +73,4 @@ In UMA, permission tickets are crucial to support person-to-person sharing and a
In the UMA workflow, permission tickets are issued by the authorization server to a resource server, which returns the permission ticket to the client trying to access a protected resource. Once the client receives the ticket, it can make a request for an RPT (a final token holding authorization data) by sending the ticket back to the authorization server.
For more information on permission tickets, see <<fake/../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization API>> and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification.
For more information on permission tickets, see <<_service_authorization_api, Authorization API>> and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification.

4
authorization_services/topics/permission/create-resource.adoc Executable file → Normal file
View file

@ -6,7 +6,7 @@ A resource-based permission defines a set of one or more resources to protect us
To create a new resource-based permission, select *Resource-based* in the dropdown list in the upper right corner of the permission listing.
.Add Resource-Based Permission
image:../../{{book.images}}/permission/create-resource.png[alt="Add Resource-Based Permission"]
image:{project_images}/permission/create-resource.png[alt="Add Resource-Based Permission"]
==== Configuration
@ -38,4 +38,4 @@ Defines a set of one or more policies to associate with a permission.
* *Decision Strategy*
+
The <<fake/../decision-strategy.adoc#_permission_decision_strategies, Decision Strategy>> for this permission.
The <<_permission_decision_strategies, Decision Strategy>> for this permission.

4
authorization_services/topics/permission/create-scope.adoc Executable file → Normal file
View file

@ -6,7 +6,7 @@ A scope-based permission defines a set of one or more scopes to protect using a
To create a new scope-based permission, select *Scope-based* in the dropdown list in the upper right corner of the permission listing.
.Add Scope-Based Permission
image:../../{{book.images}}/permission/create-scope.png[alt="Add Scope-Based Permission"]
image:{project_images}/permission/create-scope.png[alt="Add Scope-Based Permission"]
==== Configuration
@ -33,4 +33,4 @@ Defines a set of one or more policies to associate with a permission.
* *Decision Strategy*
+
The <<fake/../decision-strategy.adoc#_permission_decision_strategies, Decision Strategy>> for this permission.
The <<_permission_decision_strategies, Decision Strategy>> for this permission.

0
authorization_services/topics/permission/decision-strategy.adoc Executable file → Normal file
View file

2
authorization_services/topics/permission/overview.adoc Executable file → Normal file
View file

@ -7,7 +7,7 @@ After creating the resources you want to protect and the policies you want to us
you can start managing permissions. To manage permissions, click the *Permissions* tab when editing a resource server.
.Permissions
image:../../{{book.images}}/permission/view.png[alt="Permissions"]
image:{project_images}/permission/view.png[alt="Permissions"]
Permissions can be created to protect two main types of objects:

6
authorization_services/topics/permission/typed-resource-permission.adoc Executable file → Normal file
View file

@ -1,7 +1,7 @@
[[_permission_typed_resource]]
==== Typed Resource Permission
Resource permissions can also be used to define policies that are to be applied to all resources with a given <<fake/../../resource/create.adoc#_resource_create_type, type>>. This form of resource-based permission can be useful when you have resources sharing common access requirements and constraints.
Resource permissions can also be used to define policies that are to be applied to all resources with a given <<_resource_create_type, type>>. This form of resource-based permission can be useful when you have resources sharing common access requirements and constraints.
Frequently, resources within an application can be categorized (or typed) based on the data they encapsulate or the functionality they provide. For example, a financial application can manage different banking accounts where each one belongs to a specific customer. Although they are different banking accounts, they share common security requirements and constraints that are globally defined by the banking organization. With typed resource permissions, you can define common policies to apply to all banking accounts, such as:
@ -9,8 +9,8 @@ Frequently, resources within an application can be categorized (or typed) based
* Only allow access from the owner's country and/or region
* Enforce a specific authentication method
To create a typed resource permission, click <<fake/../create-resource.adoc#_permission_create_resource_apply_resource_type, Apply to Resource Type>> when creating a new resource-based permission. With `Apply to Resource Type` set to `On`,
To create a typed resource permission, click <<_permission_create_resource_apply_resource_type, Apply to Resource Type>> when creating a new resource-based permission. With `Apply to Resource Type` set to `On`,
you can specify the type that you want to protect as well as the policies that are to be applied to govern access to all resources with type you have specified.
.Example of a Typed Resource Permission
image:../../{{book.images}}/permission/typed-resource-perm-example.png[alt="Example of a Typed Resource Permission"]
image:{project_images}/permission/typed-resource-perm-example.png[alt="Example of a Typed Resource Permission"]

2
authorization_services/topics/policy-evaluation-tool/overview.adoc Executable file → Normal file
View file

@ -5,7 +5,7 @@ When designing your policies, you can simulate authorization requests to test ho
You can access the Policy Evaluation Tool by clicking the `Evaluate` tab when editing a resource server. There you can specify different inputs to simulate real authorization requests and test the effect of your policies.
image:../../{{book.images}}/policy-evaluation-tool/policy-evaluation-tool.png[alt="Policy Evaluation Tool"]
image:{project_images}/policy-evaluation-tool/policy-evaluation-tool.png[alt="Policy Evaluation Tool"]
=== Providing Identity Information

6
authorization_services/topics/policy/aggregated-policy.adoc Executable file → Normal file
View file

@ -1,12 +1,12 @@
[[_policy_aggregated]]
=== Aggregated Policy
As mentioned previously, {{book.project.name}} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests.
As mentioned previously, {project_name} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests.
To create a new aggregated policy, select *Aggregated* in the dropdown list located in the right upper corner of the policy listing.
.Add an Aggregated Policy
image:../../{{book.images}}/policy/create-aggregated.png[alt="Add Aggregated Policy"]
image:{project_images}/policy/create-aggregated.png[alt="Add Aggregated Policy"]
Let's suppose you have a resource called _Confidential Resource_ that can be accessed only by users from the _keycloak.org_ domain and from a certain range of IP addresses.
You can create a single policy with both conditions. However, you want to reuse the domain part of this policy to apply to permissions that operates regardless of the originating network.
@ -37,7 +37,7 @@ The decision strategy for this permission.
+
* *Logic*
+
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
==== Decision Strategy for Aggregated Policies

4
authorization_services/topics/policy/client-policy.adoc
View file

@ -6,7 +6,7 @@ You can use this type of policy to define conditions for your permissions where
To create a new client-based policy, select *Client* in the dropdown list in the upper right corner of the policy listing.
.Add a Client-Based Policy
image:../../{{book.images}}/policy/create-client.png[alt="Add Client-Based Policy"]
image:{project_images}/policy/create-client.png[alt="Add Client-Based Policy"]
==== Configuration
@ -25,4 +25,4 @@ Specifies which clients are given access by this policy.
+
* *Logic*
+
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.

8
authorization_services/topics/policy/drools-policy.adoc
View file

@ -2,13 +2,13 @@
=== Rule-Based Policy
With this type of policy you can define conditions for your permissions using http://www.drools.org[Drools], which is a rule evaluation environment. It is one of the _Rule-Based_ policy types
supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
supported by {project_name}, and provides flexibility to write any policy based on the <<_policy_evaluation_api, Evaluation API>>.
To create a new Rule-based policy, in the dropdown list in the right upper corner of the policy listing,
select *Rule*.
.Add Rule Policy
image:../../{{book.images}}/policy/create-drools.png[alt="Add Rule Policy"]
image:{project_images}/policy/create-drools.png[alt="Add Rule Policy"]
==== Configuration
@ -51,7 +51,7 @@ Specifies an interval for scanning for artifact updates.
+
* *Logic*
+
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
==== Examples
@ -89,4 +89,4 @@ rule "Authorize Using Identity Information"
end
```
For more information about what you can access from the `org.keycloak.authorization.policy.evaluation.Evaluation` interface, see <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
For more information about what you can access from the `org.keycloak.authorization.policy.evaluation.Evaluation` interface, see <<_policy_evaluation_api, Evaluation API>>.

12
authorization_services/topics/policy/evaluation-api.adoc Executable file → Normal file
View file

@ -1,7 +1,7 @@
[[_policy_evaluation_api]]
=== Policy Evaluation API
When writing rule-based policies using JavaScript or JBoss Drools, {{book.project.name}} provides an Evaluation API that provides useful information to help determine whether a permission should be granted.
When writing rule-based policies using JavaScript or JBoss Drools, {project_name} provides an Evaluation API that provides useful information to help determine whether a permission should be granted.
This API consists of a few interfaces that provides you access to information such as:
@ -40,21 +40,21 @@ public interface Evaluation {
}
```
When processing an authorization request, {{book.project.name}} creates an `Evaluation` instance before evaluating any policy. This instance is then passed to each policy to determine whether access is *GRANT* or *DENY*.
When processing an authorization request, {project_name} creates an `Evaluation` instance before evaluating any policy. This instance is then passed to each policy to determine whether access is *GRANT* or *DENY*.
Policies determine this by invoking the `grant()` or `deny()` methods on an `Evaluation` instance. By default, the state of the `Evaluation` instance is denied, which means that your policies must explicitly invoke the `grant()` method to indicate to the policy evaluation engine that permission should be granted.
{% if book.community %}
ifeval::[{project_community}==true]
For more information about the Evaluation API see the http://www.keycloak.org/docs/javadocs/index.html[JavaDocs].
{% endif %}
endif::[]
{% if book.product %}
ifeval::[{project_product}==true]
For more information about the Evaluation API see the https://access.redhat.com/webassets/avalon/d/red-hat-single-sign-on/version-7.1/javadocs/[JavaDocs].
{% endif %}
endif::[]
==== The Evaluation Context

8
authorization_services/topics/policy/js-policy.adoc
View file

@ -2,12 +2,12 @@
=== JavaScript-Based Policy
You can use this type of policy to define conditions for your permissions using JavaScript. It is one of the rule-based policy types
supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
supported by {project_name}, and provides flexibility to write any policy based on the <<_policy_evaluation_api, Evaluation API>>.
To create a new JavaScript-based policy, select *JavaScript* in the dropdown list in the upper right corner of the policy listing.
.Add JavaScript Policy
image:../../{{book.images}}/policy/create-js.png[alt="Add JavaScript Policy"]
image:{project_images}/policy/create-js.png[alt="Add JavaScript Policy"]
==== Configuration
@ -26,7 +26,7 @@ The JavaScript code providing the conditions for this policy.
+
* *Logic*
+
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
==== Examples
@ -66,4 +66,4 @@ if (identity.hasRole('admin') || email.endsWith('@keycloak.org')) {
}
```
When writing your own rules, keep in mind that the *$evaluation* object is an object implementing *org.keycloak.authorization.policy.evaluation.Evaluation*. For more information about what you can access from this interface, see the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
When writing your own rules, keep in mind that the *$evaluation* object is an object implementing *org.keycloak.authorization.policy.evaluation.Evaluation*. For more information about what you can access from this interface, see the <<_policy_evaluation_api, Evaluation API>>.

2
authorization_services/topics/policy/overview.adoc Executable file → Normal file
View file

@ -6,7 +6,7 @@ As mentioned previously, policies define the conditions that must be satisfied b
You can view all policies associated with a resource server by clicking the *Policy* tab when editing a resource server.
.Policies
image:../../{{book.images}}/policy/view.png[alt="Policies"]
image:{project_images}/policy/view.png[alt="Policies"]
On this tab, you can view the list of previously created policies as well as create and edit a policy.

2
authorization_services/topics/policy/role-policy-required-role.adoc
View file

@ -5,7 +5,7 @@ When creating a role-based policy, you can specify a specific role as `Required`
only if the user requesting access has been granted *all* the *required* roles. Both realm and client roles can be configured as such.
.Example of Required Role
image:../../{{book.images}}/policy/create-role.png[alt="Example of Required Role"]
image:{project_images}/policy/create-role.png[alt="Example of Required Role"]
To specify a role as required, select the `Required` checkbox for the role you want to configure as required.

8
authorization_services/topics/policy/role-policy.adoc
View file

@ -3,14 +3,14 @@
You can use this type of policy to define conditions for your permissions where a set of one or more roles is permitted to access an object.
By default, roles added to this policy are not specified as required and the policy will grant access if the user requesting access has been granted any of these roles. However, you can specify a specific role as <<fake/../role-policy-required-role.adoc#_policy_rbac_required, required>> if you want to enforce a specific role. You can also combine required and non-required roles, regardless of whether they are realm or client roles.
By default, roles added to this policy are not specified as required and the policy will grant access if the user requesting access has been granted any of these roles. However, you can specify a specific role as <<_policy_rbac_required, required>> if you want to enforce a specific role. You can also combine required and non-required roles, regardless of whether they are realm or client roles.
Role policies can be useful when you need more restricted role-based access control (RBAC), where specific roles must be enforced to grant access to an object. For instance, you can enforce that a user must consent to allowing a client application (which is acting on the user's behalf) to access the user's resources. You can use {{book.project.name}} Client Scope Mapping to enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {{book.project.name}} server.
Role policies can be useful when you need more restricted role-based access control (RBAC), where specific roles must be enforced to grant access to an object. For instance, you can enforce that a user must consent to allowing a client application (which is acting on the user's behalf) to access the user's resources. You can use {project_name} Client Scope Mapping to enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {project_name} server.
To create a new role-based policy, select *Role* in the dropdown list in the upper right corner of the policy listing.
.Add Role-Based Policy
image:../../{{book.images}}/policy/create-role.png[alt="Add Role-Based Policy"]
image:{project_images}/policy/create-role.png[alt="Add Role-Based Policy"]
==== Configuration
@ -33,4 +33,4 @@ Specifies which *client* roles are permitted by this policy. To enable this fiel
+
* *Logic*
+
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.

6
authorization_services/topics/policy/time-policy.adoc
View file

@ -6,7 +6,7 @@ You can use this type of policy to define time conditions for your permissions.
To create a new time-based policy, select *Time* in the dropdown list in the upper right corner of the policy listing.
.Add Time Policy
image:../../{{book.images}}/policy/create-time.png[alt="Add Time Policy"]
image:{project_images}/policy/create-time.png[alt="Add Time Policy"]
==== Configuration
@ -50,6 +50,6 @@ Defines the minute that access must be granted. You can also specify a range of
+
* *Logic*
+
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
Access is only granted if all conditions are satisfied. {{book.project.name}} will perform an _AND_ based on the outcome of each condition.
Access is only granted if all conditions are satisfied. {project_name} will perform an _AND_ based on the outcome of each condition.

4
authorization_services/topics/policy/user-policy.adoc
View file

@ -6,7 +6,7 @@ You can use this type of policy to define conditions for your permissions where
To create a new user-based policy, select *User* in the dropdown list in the upper right corner of the policy listing.
.Add a User-Based Policy
image:../../{{book.images}}/policy/create-user.png[alt="Add User-Based Policy"]
image:{project_images}/policy/create-user.png[alt="Add User-Based Policy"]
==== Configuration
@ -25,4 +25,4 @@ Specifies which users are given access by this policy.
+
* *Logic*
+
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.

8
authorization_services/topics/resource-server/create-client.adoc Executable file → Normal file
View file

@ -1,19 +1,19 @@
[[_resource_server_create_client]]
=== Creating a Client Application
The first step to enable {{book.project.name}} {{book.project.module}} is to create the client application that you want to turn into a resource server.
The first step to enable {project_name} Authorization Services is to create the client application that you want to turn into a resource server.
To create a client application, complete the following steps:
. Click *Clients*.
+
.Clients
image:../../{{book.images}}/resource-server/client-list.png[alt="Clients"]
image:{project_images}/resource-server/client-list.png[alt="Clients"]
. On this page, click *Create*.
+
.Create Client
image:../../{{book.images}}/resource-server/client-create.png[alt="Create Client"]
image:{project_images}/resource-server/client-create.png[alt="Create Client"]
. Type the `Client ID` of the client. For example, _my-resource-server_.
. Type the `Root URL` for your application. For example:
@ -25,4 +25,4 @@ http://${host}:${port}/my-resource-server
. Click *Save*. The client is created and the client Settings page opens. A page similar to the following is displayed:
+
.Client Settings
image:../../{{book.images}}/resource-server/client-enable-authz.png[alt="Client Settings"]
image:{project_images}/resource-server/client-enable-authz.png[alt="Client Settings"]

20
authorization_services/topics/resource-server/default-config.adoc Executable file → Normal file
View file

@ -1,7 +1,7 @@
[[_resource_server_default_config]]
=== Default Configuration
When you create a resource server, {{book.project.name}} creates a default configuration for your newly created resource server.
When you create a resource server, {project_name} creates a default configuration for your newly created resource server.
The default configuration consists of:
@ -12,22 +12,22 @@ The default configuration consists of:
The default protected resource is referred to as the *default resource* and you can view it if you navigate to the *Resources* tab.
.Default Resource
image:../../{{book.images}}/resource-server/default-resource.png[alt="Default Resource"]
image:{project_images}/resource-server/default-resource.png[alt="Default Resource"]
This resource defines a `Type`, namely `urn:my-resource-server:resources:default` and a `URI` `/*`. Here, the `URI` field defines a
wildcard pattern that indicates to {{book.project.name}} that this resource represents all the paths in your application. In other words,
when enabling <<fake/../../enforcer/overview.adoc#_enforcer_overview, policy enforcement>> for your application, all the permissions associated with the resource
wildcard pattern that indicates to {project_name} that this resource represents all the paths in your application. In other words,
when enabling <<_enforcer_overview, policy enforcement>> for your application, all the permissions associated with the resource
will be examined before granting access.
The `Type` mentioned previously defines a value that can be used to create <<fake/../../permission/typed-resource-permission.adoc#_permission_typed_resource, typed resource permissions>> that must be applied
The `Type` mentioned previously defines a value that can be used to create <<_permission_typed_resource, typed resource permissions>> that must be applied
to the default resource or any other resource you create using the same type.
The default policy is referred to as the *only from realm policy* and you can view it if you navigate to the *Policies* tab.
.Default Policy
image:../../{{book.images}}/resource-server/default-policy.png[alt="Default Policy"]
image:{project_images}/resource-server/default-policy.png[alt="Default Policy"]
This policy is a <<fake/../../policy/js-policy.adoc#_policy_js, JavaScript-based policy>> defining a condition that always grants access to the resources protected by this policy. If you click this policy you can see that it defines a rule as follows:
This policy is a <<_policy_js, JavaScript-based policy>> defining a condition that always grants access to the resources protected by this policy. If you click this policy you can see that it defines a rule as follows:
```js
// by default, grants any permission associated with this policy
@ -37,13 +37,13 @@ $evaluation.grant();
Lastly, the default permission is referred to as the *default permission* and you can view it if you navigate to the *Permissions* tab.
.Default Permission
image:../../{{book.images}}/resource-server/default-permission.png[alt="Default Permission"]
image:{project_images}/resource-server/default-permission.png[alt="Default Permission"]
This permission is a <<fake/../../permission/create-resource.adoc#_permission_create_resource, resource-based permission>>, defining a set of one or more policies that are applied to all resources with a given type.
This permission is a <<_permission_create_resource, resource-based permission>>, defining a set of one or more policies that are applied to all resources with a given type.
==== Changing the Default Configuration
You can change the default configuration by removing the default resource, policy, or permission definitions and creating your own.
[NOTE]
The default configuration defines a resource that maps to all paths in your application. If you are about to write permissions to your own resources, be sure to remove the *Default Resource* or change its ```URI``` field to a more specific path in your application. Otherwise, the policy associated with the default resource (which by default always grants access) will allow {{book.project.name}} to grant access to any protected resource.
The default configuration defines a resource that maps to all paths in your application. If you are about to write permissions to your own resources, be sure to remove the *Default Resource* or change its ```URI``` field to a more specific path in your application. Otherwise, the policy associated with the default resource (which by default always grants access) will allow {project_name} to grant access to any protected resource.

14
authorization_services/topics/resource-server/enable-authorization.adoc Executable file → Normal file
View file

@ -4,12 +4,12 @@
To turn your OIDC Client Application into a resource server and enable fine-grained authorization, click the *Authorization Enabled* switch to *ON* and click *Save*.
.Enabling Authorization Services
image:../../{{book.images}}/resource-server/client-enable-authz.png[alt="Enabling Authorization Services"]
image:{project_images}/resource-server/client-enable-authz.png[alt="Enabling Authorization Services"]
A new Authorization tab is displayed for this client. Click the *Authorization* tab and a page similar to the following is displayed:
.Resource Server Settings
image:../../{{book.images}}/resource-server/authz-settings.png[alt="Resource Server Settings"]
image:{project_images}/resource-server/authz-settings.png[alt="Resource Server Settings"]
The Authorization tab contains additional sub-tabs covering the different steps that you must follow to actually protect your application's resources. Each tab is covered separately by a specific topic in this documentation. But here is a quick description about each one:
@ -19,23 +19,23 @@ General settings for your resource server. For more details about this page see
* *Resource*
+
From this page, you can manage your application's <<fake/../../resource/overview.adoc#_resource_overview, resources>>.
From this page, you can manage your application's <<_resource_overview, resources>>.
* *Scope*
+
From this page, you can manage <<fake/../../resource/overview.adoc#_resource_overview, scopes>>.
From this page, you can manage <<_resource_overview, scopes>>.
* *Policies*
+
From this page, you can manage <<fake/../../policy/overview.adoc#_policy_overview, authorization policies>> and define the conditions that must be met to grant a permission.
From this page, you can manage <<_policy_overview, authorization policies>> and define the conditions that must be met to grant a permission.
* *Permissions*
+
From this page, you can manage the <<fake/../../permission/overview.adoc#_permission_overview, permissions>> for your protected resources and scopes by linking them with the policies you created.
From this page, you can manage the <<_permission_overview, permissions>> for your protected resources and scopes by linking them with the policies you created.
* *Evaluate*
+
From this page, you can <<fake/../../policy-evaluation-tool/overview.adoc#_policy_evaluation_overview, simulate authorization requests>> and view the result of the evaluation of the permissions and authorization policies you have defined.
From this page, you can <<_policy_evaluation_overview, simulate authorization requests>> and view the result of the evaluation of the permissions and authorization policies you have defined.
[[resource_server_settings]]
==== Resource Server Settings

4
authorization_services/topics/resource-server/import-config.adoc Executable file → Normal file
View file

@ -14,12 +14,12 @@ To export a configuration file, complete the following steps:
. Navigate to the *Resource Server Settings* page.
+
.Resource Server Settings
image:../../{{book.images}}/resource-server/authz-settings.png[alt="Resource Server Settings"]
image:{project_images}/resource-server/authz-settings.png[alt="Resource Server Settings"]
. On this page, in the Export Settings section, click *Export*.
+
.Export Settings
image:../../{{book.images}}/resource-server/authz-export.png[alt="Export Settings"]
image:{project_images}/resource-server/authz-export.png[alt="Export Settings"]
The configuration file is exported in JSON format and displayed in a text area, from which you can copy and paste. You can also click *Download* to download the configuration file and save it.

2
authorization_services/topics/resource-server/overview.adoc Executable file → Normal file
View file

@ -3,6 +3,6 @@
According to the OAuth2 specification, a resource server is a server hosting the protected resources and capable of accepting and responding to protected resource requests.
In {{book.project.name}}, resource servers are provided with a rich platform for enabling fine-grained authorization for their protected resources, where authorization decisions can be made based on different access control mechanisms.
In {project_name}, resource servers are provided with a rich platform for enabling fine-grained authorization for their protected resources, where authorization decisions can be made based on different access control mechanisms.
Any client application can be configured to support fine-grained permissions. In doing so, you are conceptually turning the client application into a resource server.

8
authorization_services/topics/resource/create.adoc Executable file → Normal file
View file

@ -7,9 +7,9 @@ be created to represent a set of one or more resources and the way you define th
To create a new resource, click *Create* in the right upper corner of the resource listing.
.Add Resource
image:../../{{book.images}}/resource/create.png[alt="Add Resource"]
image:{project_images}/resource/create.png[alt="Add Resource"]
In {{book.project.name}}, a resource defines a small set of information that is common to different types of resources, such as:
In {project_name}, a resource defines a small set of information that is common to different types of resources, such as:
* *Name*
+
@ -42,11 +42,11 @@ However, resources can also be associated with users, so you can create permissi
==== Managing Resources Remotely
Resource management is also exposed through the <<fake/../../service/protection/protection-api.adoc#_service_protection_api, Protection API>> to allow resource servers to remotely manage their resources.
Resource management is also exposed through the <<_service_protection_api, Protection API>> to allow resource servers to remotely manage their resources.
When using the Protection API, resource servers can be implemented to manage resources owned by their users. In this case, you can
specify the user identifier to configure a resource as belonging to a specific user.
[NOTE]
{{book.project.name}} provides resource servers complete control over their resources. In the future, we should be able to
{project_name} provides resource servers complete control over their resources. In the future, we should be able to
allow users to control their own resources as well as approve authorization requests and manage permissions, especially when using the UMA protocol.

0
authorization_services/topics/resource/overview.adoc Executable file → Normal file
View file

2
authorization_services/topics/resource/view.adoc Executable file → Normal file
View file

@ -4,7 +4,7 @@
On the *Resource* page, you see a list of the resources associated with a resource server.
.Resources
image:../../{{book.images}}/resource/view.png[alt="Resources"]
image:{project_images}/resource/view.png[alt="Resources"]
The resource list provides information about the protected resources, such as:

6
authorization_services/topics/service/authorization/authorization-api-aapi.adoc Executable file → Normal file
View file

@ -1,7 +1,7 @@
[[_service_authorization_api_aapi]]
==== Requesting Authorization Data and Token
Client applications using the UMA protocol can use a specific endpoint to obtain a special security token called a <<fake/../../rpt/overview.adoc#_service_rpt_overview, Requesting Party Token (RPT)>>.
Client applications using the UMA protocol can use a specific endpoint to obtain a special security token called a <<_service_rpt_overview, Requesting Party Token (RPT)>>.
This token consists of all the permissions granted to a user as a result of the evaluation of the permissions and authorization policies associated with the resources being requested.
With an RPT, client applications can gain access to protected resources at the resource server.
@ -12,8 +12,8 @@ http://${host}:${port}/auth/realms/${realm_name}/authz/authorize
When requesting an RPT, you need to provide two things:
* A <<fake/../../protection/permission-api-papi.adoc#_service_protection_permission_api_papi, permission ticket>> representing the resources you want to access
* The <<fake/../whatis-obtain-aat.adoc#_service_authorization_aat, Authorization API token (AAT)>> (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf.
* A <<_service_protection_permission_api_papi, permission ticket>> representing the resources you want to access
* The <<_service_authorization_aat, Authorization API token (AAT)>> (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf.
The permission ticket is added to a HTTP request as a parameter whether the AAT is included in a ```Authorization``` header in order to authenticate de request
using the AAT as a bearer token.

0
authorization_services/topics/service/authorization/authorization-api.adoc Executable file → Normal file
View file

8
authorization_services/topics/service/authorization/whatis-obtain-aat.adoc Executable file → Normal file
View file

@ -1,16 +1,16 @@
[[_service_authorization_aat]]
==== What is an AAT and How to Obtain It
An authorization API token (AAT) is a special OAuth2 access token with the scope *uma_authorization*. When you create a user, {{book.project.name}} automatically
An authorization API token (AAT) is a special OAuth2 access token with the scope *uma_authorization*. When you create a user, {project_name} automatically
assigns the role _uma_authorization_ to the user. The _uma_authorization_ role is a default realm role.
.Default Role uma_authorization
image:../../../{{book.images}}/service/rs-uma-authorization-role.png[alt="Default Role uma_authorization "]
image:{project_images}/service/rs-uma-authorization-role.png[alt="Default Role uma_authorization "]
An AAT enables a client application to query the server for user permissions.
Client applications can obtain an AAT from {{book.project.name}} like any other OAuth2 access token. Usually, client applications obtain AATs after the user is successfully
authenticated in {{book.project.name}}. By default, the _authorization_code_ grant type is used to authenticate users, and the server will issue an OAuth2 access token to the client application acting on their behalf.
Client applications can obtain an AAT from {project_name} like any other OAuth2 access token. Usually, client applications obtain AATs after the user is successfully
authenticated in {project_name}. By default, the _authorization_code_ grant type is used to authenticate users, and the server will issue an OAuth2 access token to the client application acting on their behalf.
The example below uses the Resource Owner Password Credentials Grant Type to request an AAT:

4
authorization_services/topics/service/client-api.adoc Executable file → Normal file
View file

@ -2,7 +2,7 @@
=== Authorization Client Java API
Depending on your requirements, a resource server should be able to manage resources remotely or even check for permissions programmatically.
If you are using Java, you can access the {{book.project.name}} Authorization Services using the Authorization Client API.
If you are using Java, you can access the {project_name} Authorization Services using the Authorization Client API.
It is targeted for resource servers that want to access the different APIs provided by the server such as the Protection, Authorization and Entitlement APIs.
@ -39,7 +39,7 @@ The name of the realm.
* *auth-server-url* (required)
+
The base URL of the {{book.project.name}} server. All other {{book.project.name}} pages and REST service endpoints are derived from this. It is usually in the form https://host:port/auth.
The base URL of the {project_name} server. All other {project_name} pages and REST service endpoints are derived from this. It is usually in the form https://host:port/auth.
* *resource* (required)
+

12
authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc Executable file → Normal file
View file

@ -1,7 +1,7 @@
[[_service_entitlement_api_aapi]]
==== Requesting Entitlements
Client applications can use a specific endpoint to obtain a special security token called a <<fake/../../rpt/overview.adoc#_service_rpt_overview, Requesting Party Token (RPT)>>.
Client applications can use a specific endpoint to obtain a special security token called a <<_service_rpt_overview, Requesting Party Token (RPT)>>.
This token consists of all the entitlements (or permissions) for a user as a result of the evaluation of the permissions and authorization policies associated with the resources being requested.
With an RPT, client applications can gain access to protected resources at the resource server.
@ -10,8 +10,8 @@ With an RPT, client applications can gain access to protected resources at the r
http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement/{client_id}
```
The **client_id** parameter above must be provided in order to identify the client application acting as a <<fake/../../../overview/terminology.adoc#_overview_terminology_resource_server, resource server>>
in {{book.project.name}}. You must provide the client identifier in order to restrict the scope of the evaluation to the resources, scopes and permissions
The **client_id** parameter above must be provided in order to identify the client application acting as a <<_overview_terminology_resource_server, resource server>>
in {project_name}. You must provide the client identifier in order to restrict the scope of the evaluation to the resources, scopes and permissions
managed by a specific resource server.
The Entitlement API comes in two flavors:
@ -22,14 +22,14 @@ owned and managed by the resource server itself.
* Using HTTP **POST** in order to obtain entitlements based on a a set of one or more resources and scopes sent along with an entitlement request.
[NOTE]
Using one or another depends on your use case and how much resources you have registered in {{book.project.name}}. Although the **GET** variant
Using one or another depends on your use case and how much resources you have registered in {project_name}. Although the **GET** variant
provides an easy way to obtain entitlements from the server, it might not be appropriate in case you have too much resources associated
with an user. In this case, the **POST** method is recommended.
Regardless of the HTTP method you decide to use, the Entitlement API endpoint expects an access token in the request representing a user's identity
and his consent to access authorization data on his behalf. The access token must be sent as a bearer token using a HTTP ```Authorization``` header.
After successfully invoking the Entitlement API endpoint, you will get a <<fake/../../rpt/overview.adoc#_service_rpt_overview, RPT>> with all permissions
After successfully invoking the Entitlement API endpoint, you will get a <<_service_rpt_overview, RPT>> with all permissions
granted by the server.
===== Obtaining Entitlements
@ -51,7 +51,7 @@ As a result, the server response is:
```
Using this method to obtain entitlements, the server responds to the requesting client with *all* entitlements for a user, based on the evaluation of the permissions and
authorization policies associated with the resources owned by the user or the resource server itself. For instance, suppose you have permissions defined in {{book.project.name}} for the following resources:
authorization policies associated with the resources owned by the user or the resource server itself. For instance, suppose you have permissions defined in {project_name} for the following resources:
* Main Page
* Alice Bank Account

0
authorization_services/topics/service/entitlement/entitlement-api.adoc Executable file → Normal file
View file

0
authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc Executable file → Normal file
View file

4
authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc Executable file → Normal file
View file

@ -3,8 +3,8 @@
An entitlement API token (EAT) is a special OAuth2 access token with the scope *kc_entitlement*.
Client applications can obtain an EAT from {{book.project.name}} like any other OAuth2 access token. Usually, client applications obtain EATs after the user is successfully
authenticated in {{book.project.name}}. By default the _authorizaton_code_ grant type is used to authenticate a user and issue an OAuth2 access token to the client application acting on the user's behalf.
Client applications can obtain an EAT from {project_name} like any other OAuth2 access token. Usually, client applications obtain EATs after the user is successfully
authenticated in {project_name}. By default the _authorizaton_code_ grant type is used to authenticate a user and issue an OAuth2 access token to the client application acting on the user's behalf.
For demonstration purposes, the example below uses Resource Owner Password Credentials Grant Type to request an EAT:

2
authorization_services/topics/service/overview.adoc Executable file → Normal file
View file

@ -1,7 +1,7 @@
[[_service_overview]]
== Authorization Services
{{book.project.name}} {{book.project.module}} are based on OAuth2's User-Managed Access (UMA) Profile.
{project_name} Authorization Services are based on OAuth2's User-Managed Access (UMA) Profile.
This section describes the different RESTful endpoints that you can interact with to enable fine-grained authorization
for your applications and services.

10
authorization_services/topics/service/protection/permission-api-papi.adoc Executable file → Normal file
View file

@ -7,23 +7,23 @@ Resource servers using the UMA protocol can use a specific endpoint to manage pe
http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission
```
A <<fake/../../../overview/terminology.adoc#_overview_terminology_permission_ticket, permission ticket>> is a special security token type representing a permission request. Per the UMA specification, a permission ticket is:
A <<_overview_terminology_permission_ticket, permission ticket>> is a special security token type representing a permission request. Per the UMA specification, a permission ticket is:
`A correlation handle that is conveyed from an authorization server to a resource server, from a resource server to a client, and ultimately from a client back to an authorization server, to enable the authorization server to assess the correct policies to apply to a request for authorization data.`
[NOTE]
_Permission ticket support is limited_.
In the full UMA protocol, resource servers can register permission requests in the server to support authorization flows where a resource owner (the user that owns a resource being requested) can approve access to his resources by third parties, among other ways. This represents one of the main features of the UMA specification: resource owners can control their own resources and the policies that govern them. Currently {{book.project.name}} UMA implementation support is very limited in this regard. For example, the system does not store permission tickets on the server and we are essentially using UMA to provide API security and base our authorization offerings. In the future, full support of UMA and other use cases is planned.
In the full UMA protocol, resource servers can register permission requests in the server to support authorization flows where a resource owner (the user that owns a resource being requested) can approve access to his resources by third parties, among other ways. This represents one of the main features of the UMA specification: resource owners can control their own resources and the policies that govern them. Currently {project_name} UMA implementation support is very limited in this regard. For example, the system does not store permission tickets on the server and we are essentially using UMA to provide API security and base our authorization offerings. In the future, full support of UMA and other use cases is planned.
In most cases, you won't need to deal with this endpoint directly. {{book.project.name}} provides a <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcer>> that enables UMA for your
In most cases, you won't need to deal with this endpoint directly. {project_name} provides a <<_enforcer_overview, policy enforcer>> that enables UMA for your
resource server so it can obtain a permission ticket from the authorization server, return this ticket to client application, and enforce authorization decisions based on a final requesting party token (RPT).
The process of obtaining permission tickets from {{book.project.name}} is performed by resource servers and not regular client applications,
The process of obtaining permission tickets from {project_name} is performed by resource servers and not regular client applications,
where permission tickets are obtained when a client tries to access a protected resource without the necessary grants to access the resource. The issuance of
permission tickets is an important aspects when using UMA as it allows resource servers to:
* Abstract from clients the data associated with the resources protected by the resource server
* Register in the {{book.project.name}} authorization requests which in turn can be used later in workflows to grant access based on the resource's owner consent
* Register in the {project_name} authorization requests which in turn can be used later in workflows to grant access based on the resource's owner consent
* Decouple resource servers from authorization servers and allow them to protect and manage their resources using different authorization servers
Client wise, a permission ticket has also important aspects that its worthy to highlight:

2
authorization_services/topics/service/protection/protection-api.adoc Executable file → Normal file
View file

@ -5,7 +5,7 @@ The Protection API provides a UMA-compliant set of endpoints providing:
* *Resource Registration*
+
With this endpoint, resource servers can manage their resources remotely and enable <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcers>> to query the server for the resources that need protection.
With this endpoint, resource servers can manage their resources remotely and enable <<_enforcer_overview, policy enforcers>> to query the server for the resources that need protection.
* *Permission Registration*
+

0
authorization_services/topics/service/protection/resources-api-papi.adoc Executable file → Normal file
View file

8
authorization_services/topics/service/protection/whatis-obtain-pat.adoc Executable file → Normal file
View file

@ -1,13 +1,13 @@
[[_service_protection_whatis_obtain_pat]]
==== What is a PAT and How to Obtain It
A *protection API token* (PAT) is a special OAuth2 access token with a scope defined as *uma_protection*. When you create a resource server, {{book.project.name}} automatically
A *protection API token* (PAT) is a special OAuth2 access token with a scope defined as *uma_protection*. When you create a resource server, {project_name} automatically
creates a role, _uma_protection_, for the corresponding client application and associates it with the client's service account.
.Service Account granted with *uma_protection* role
image:../../../{{book.images}}/service/rs-uma-protection-role.png[alt="Service Account granted with uma_protection role"]
image:{project_images}/service/rs-uma-protection-role.png[alt="Service Account granted with uma_protection role"]
Resource servers can obtain a PAT from {{book.project.name}} like any other OAuth2 access token. For example, using curl:
Resource servers can obtain a PAT from {project_name} like any other OAuth2 access token. For example, using curl:
```bash
curl -X POST \
@ -33,5 +33,5 @@ The example above is using the *client_credentials* grant type to obtain a PAT f
```
[NOTE]
{{book.project.name}} can authenticate your client application in different ways. For simplicity, the *client_credentials* grant type is used here,
{project_name} can authenticate your client application in different ways. For simplicity, the *client_credentials* grant type is used here,
which requires a _client_id_ and a _client_secret_. You can choose to use any supported authentication method.

2
authorization_services/topics/service/rpt/overview.adoc
View file

@ -1,7 +1,7 @@
[[_service_rpt_overview]]
==== Requesting Party Token
A requesting party token (RPT) is a https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON web signature (JWS)]. The token is built based on the OAuth2 access token previously issued by {{book.project.name}} to a specific client acting on behalf of an user
A requesting party token (RPT) is a https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON web signature (JWS)]. The token is built based on the OAuth2 access token previously issued by {project_name} to a specific client acting on behalf of an user
or on its own behalf.
When you decode an RPT, you see a payload similar to the following:

8
authorization_services/topics/service/rpt/token-introspection.adoc Executable file → Normal file
View file

@ -6,7 +6,7 @@ Sometimes you might want to introspect a requesting party token (RPT) to check i
There are two main use cases where token introspection can help you:
* When client applications need to query the token validity to obtain a new one with the same or additional permissions
* When enforcing authorization decisions at the resource server side, especially when none of the built-in <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcers>> fits your application
* When enforcing authorization decisions at the resource server side, especially when none of the built-in <<_enforcer_overview, policy enforcers>> fits your application
==== Obtaining Information about an RPT
@ -27,7 +27,7 @@ curl -X POST \
```
[NOTE]
The request above is using HTTP BASIC and passing the client's credentials (client ID and secret) to authenticate the client attempting to introspect the token, but you can use any other client authentication method supported by {{book.project.name}}.
The request above is using HTTP BASIC and passing the client's credentials (client ID and secret) to authenticate the client attempting to introspect the token, but you can use any other client authentication method supported by {project_name}.
The introspection endpoint expects two parameters:
@ -67,13 +67,13 @@ If the RPT is not active, this response is returned instead:
==== Do I Need to Invoke the Server Every Time I Want to Introspect an RPT?
No. Both <<fake/../../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization>> and <<fake/../../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement>> APIs use the
No. Both <<_service_entitlement_api, Entitlement>> APIs use the
https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] specification as the default format for RPTs.
If you want to validate these tokens without a call to the remote introspection endpoint, you can decode the RPT and query for its validity locally. Once you decode the token,
you can also use the permissions within the token to enforce authorization decisions.
This is essentially what the <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcers>> do. Be sure to:
This is essentially what the <<_enforcer_overview, policy enforcers>> do. Be sure to:
* Validate the signature of the RPT (based on the realm's public key)
* Query for token validity based on its _exp_, _iat_, and _aud_ claims

20
build-product.sh → convert.sh
View file

@ -38,25 +38,7 @@ function buildGuide
echo "$TOOL: $GUIDE"
echo ""
cd $GUIDE
rm -rf build
rm -rf target
python ../gitlab-conversion.py
if [ "$TOOL" = "asciidoctor" ]; then
asciidoctor -dbook -a toc -o target/master.html target/master.adoc
echo ""
echo "Built file://$CURRENT_DIRECTORY/$GUIDE/target/master.html"
fi
if [ "$TOOL" = "ccutil" ]; then
ccutil compile --lang en_US --format html-single --main-file target/master.adoc
echo ""
echo "Built file://$CURRENT_DIRECTORY/$GUIDE/build/tmp/en-US/html-single/index.html"
fi
cd ..
cp /home/st/tmp/keycloak-documentation/$GUIDE/pom.xml $GUIDE/
}
if [ "$GUIDE" = "" ]; then

52
document-attributes-community.adoc Normal file
View file

@ -0,0 +1,52 @@
:project_name: Keycloak
:project_community: true
:project_product: false
:project_version: 3.3.0.CR1
:project_versionMvn: 3.3.0.CR1
:project_versionNpm: 3.3.0-cr.1
:project_images: keycloak-images
:project_doc_base_url: http://www.keycloak.org/documentation.html
:project_doc_info_version_url: 3.3
:quickstartRepo_link: https://github.com/keycloak/keycloak-quickstarts
:quickstartRepo_name: Keycloak Quickstarts Repository
:quickstartRepo_dir: keycloak-quickstarts
:adapterguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/securing-applications-and-services-guide/
:adapterguide_name: Securing Applications and Services Guide
:adminguide_link: https://keycloak.gitbooks.io/documentation/content/server_admin/index.html
:adminguide_name: Server Administration
:apidocs_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/api-documentation/
:apidocs_name: API Documentation
:developerguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-developer-guide/
:developerguide_name: Server Development
:gettingstarted_link: {project_doc_base_url}/{project_doc_info_version_url}/html/getting-started-guide/
:gettingstarted_name: Getting Started Tutorial
:installguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-installation-and-configuration-guide/
:installguide_name: Server Installation and Configuration
:installguide_profile_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-installation-and-configuration-guide/#profiles
:installguide_profile_name: Profiles
:appserver_name: JBoss EAP
:appserver_doc_base_url: https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform
:appserver_version: {appserver_version}
:appserver_socket_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#network_and_port_configuration
:appserver_socket_name: JBoss EAP Configuration Guide
:appserver_jgroups_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#cluster_communication_jgroups
:appserver_jgroups_name: JBoss EAP Configuration Guide
:appserver_jpa_link: {appserver_doc_base_url}/{appserver_version}/html-single/development-guide/#hibernate
:appserver_jpa_name: JBoss EAP Development Guide
:appserver_network_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#network_and_port_configuration
:appserver_network_name: JBoss EAP Configuration Guide
:appserver_datasource_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#datasource_management
:appserver_datasource_name: JBoss EAP Configuration Guide
:appserver_caching_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#infinispan
:appserver_caching_name: JBoss EAP Configuration Guide
:appserver_admindoc_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/configuration-guide
:appserver_admindoc_name: JBoss EAP Configuration Guide
:appserver_loadbalancer_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#configuring_high_availability
:appserver_loadbalancer_name: JBoss EAP Configuration Guide
:fuseVersion: JBoss Fuse 6.3.0 Rollup 1
:subsystem_undertow_xml_urn: urn:jboss:domain:undertow:3.1

52
document-attributes-product.adoc Normal file
View file

@ -0,0 +1,52 @@
:project_name: Red Hat Single Sign-On
:project_community: false
:project_product: true
:project_version: 7.2.0.DR4
:project_versionMvn: 3.3.0.Final-redhat1
:project_versionNpm: 3.3.0.Final-redhat1
:project_images: rhsso-images
:project_doc_base_url: https://access.redhat.com/documentation/en/red-hat-single-sign-on/
:project_doc_info_version_url: 7.2
:quickstartRepo_link: https://github.com/keycloak/keycloak-quickstarts
:quickstartRepo_name: Keycloak Quickstarts Repository
:quickstartRepo_dir: keycloak-quickstarts
:adapterguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/securing-applications-and-services-guide/
:adapterguide_name: Securing Applications and Services Guide
:adminguide_link: https://keycloak.gitbooks.io/documentation/content/server_admin/index.html
:adminguide_name: Server Administration
:apidocs_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/api-documentation/
:apidocs_name: API Documentation
:developerguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-developer-guide/
:developerguide_name: Server Development
:gettingstarted_link: {project_doc_base_url}/{project_doc_info_version_url}/html/getting-started-guide/
:gettingstarted_name: Getting Started Tutorial
:installguide_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-installation-and-configuration-guide/
:installguide_name: Server Installation and Configuration
:installguide_profile_link: {project_doc_base_url}/{project_doc_info_version_url}/html-single/server-installation-and-configuration-guide/#profiles
:installguide_profile_name: Profiles
:appserver_name: JBoss EAP
:appserver_doc_base_url: https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform
:appserver_version: {appserver_version}
:appserver_socket_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#network_and_port_configuration
:appserver_socket_name: JBoss EAP Configuration Guide
:appserver_jgroups_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#cluster_communication_jgroups
:appserver_jgroups_name: JBoss EAP Configuration Guide
:appserver_jpa_link: {appserver_doc_base_url}/{appserver_version}/html-single/development-guide/#hibernate
:appserver_jpa_name: JBoss EAP Development Guide
:appserver_network_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#network_and_port_configuration
:appserver_network_name: JBoss EAP Configuration Guide
:appserver_datasource_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#datasource_management
:appserver_datasource_name: JBoss EAP Configuration Guide
:appserver_caching_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#infinispan
:appserver_caching_name: JBoss EAP Configuration Guide
:appserver_admindoc_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/configuration-guide
:appserver_admindoc_name: JBoss EAP Configuration Guide
:appserver_loadbalancer_link: {appserver_doc_base_url}/{appserver_version}/html-single/configuration-guide/#configuring_high_availability
:appserver_loadbalancer_name: JBoss EAP Configuration Guide
:fuseVersion: JBoss Fuse 6.3.0 Rollup 1
:subsystem_undertow_xml_urn: urn:jboss:domain:undertow:3.1

9
getting_started/README.adoc
View file

@ -1,9 +0,0 @@
= Getting Started
image:images/keycloak_logo.png[alt="Keycloak"]
{{book.project.name}} {{book.project.version}}
http://www.keycloak.org

24
getting_started/SUMMARY.adoc
View file

@ -1,24 +0,0 @@
= Getting Started Guide
.. link:getting_started/topics/overview.adoc[Overview]
.. link:getting_started/topics/first-boot.adoc[Installing and Booting]
{% if book.community %}
... link:getting_started/topics/first-boot/distribution-files-community.adoc[Installing the Server]
{% endif %}
{% if book.product %}
... link:getting_started/topics/first-boot/distribution-files-product.adoc[Installing the Server]
{% endif %}
... link:getting_started/topics/first-boot/boot.adoc[Booting the Server]
... link:getting_started/topics/first-boot/initial-user.adoc[Creating the Admin Account]
... link:getting_started/topics/first-boot/admin-console.adoc[Logging in to the Admin Console]
.. link:getting_started/topics/first-realm.adoc[Creating Your First Realm and User]
... link:getting_started/topics/first-realm/before.adoc[Before You Start]
... link:getting_started/topics/first-realm/realm.adoc[Creating a New Realm]
... link:getting_started/topics/first-realm/user.adoc[Creating a New User]
... link:getting_started/topics/first-realm/account.adoc[User Account Service]
.. link:getting_started/topics/secure-jboss-app.adoc[Securing a JBoss Servlet Application]
... link:getting_started/topics/secure-jboss-app/before.adoc[Before You Start]
... link:getting_started/topics/secure-jboss-app/install-client-adapter.adoc[Installing the Client Adapter]
... link:getting_started/topics/secure-jboss-app/download-quickstarts.adoc[Downloading, Building, and Deploying Application Code]
... link:getting_started/topics/secure-jboss-app/create-client.adoc[Creating and Registering the Client]
... link:getting_started/topics/secure-jboss-app/subsystem.adoc[Configuring the Subsystem]

47
getting_started/book-product.json
View file

@ -1,47 +0,0 @@
{
"gitbook": "2.x.x",
"structure": {
"readme": "README.adoc"
},
"plugins": [
"toggle-chapters",
"ungrey",
"splitter"
],
"variables": {
"title": "Getting Started Guide",
"project": {
"name": "Red Hat Single Sign-On",
"version": "7.1.0",
"doc_base_url": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/",
"doc_info_version_url": "7.1"
},
"community": false,
"product": true,
"images": "rhsso-images",
"installguide": {
"name": "Server Installation and Configuration Guide",
"link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-installation-and-configuration-guide/"
},
"adminguide": {
"name": "Server Administration Guide",
"link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/server-administration-guide/"
},
"clientadapter": "RH-SSO-{{book.project.version}}-eap7-adapter.zip",
"appServer": "JBoss EAP 7",
"appserver": {
"name": "JBoss EAP 7"
},
"quickstartRepo": {
"name": "Quickstarts for the Red Hat Single Sign-On (SSO) Server",
"dir": "redhat-sso-quickstarts",
"link": "https://github.com/redhat-developer/redhat-sso-quickstarts"
},
"subsystem": {
"undertow": "urn:jboss:domain:undertow:3.1"
}
}
}

80
getting_started/buildGuide.sh
View file

@ -1,80 +0,0 @@
# Build the guide
# Find the directory name and full path
CURRENT_GUIDE=${PWD##*/}
CURRENT_DIRECTORY=$(pwd)
usage(){
cat <<EOM
USAGE: $0 [OPTION]
DESCRIPTION: Build the documentation in this directory.
OPTIONS:
-h Print help.
EOM
}
while getopts "ht:" c
do
case "$c" in
h) usage
exit 1;;
\?) echo "Unknown option: -$OPTARG." >&2
usage
exit 1;;
esac
done
echo ""
echo "********************************************"
echo " Building $CURRENT_GUIDE "
echo "********************************************"
if [ ! -d target ]; then
echo "You must run 'python gitlab-conversion.py' to convert the content before you run this script."
exit
fi
# Remove the guide directory path from the master.adoc file as it is not needed
echo ""
echo "***************************************************************************************"
echo "Removing the guide directory path from the master.adoc file as it is not needed."
echo "NOTE: The guide directory path should probably be removed from the SUMMARY.adoc file,"
echo "but since we do not know if it will break the upstream build, we are doing this here. "
echo "If it can not be removed from the SUMMARY.adoc file, this should really be done in the "
echo "Python script because otherwise you must run this script before porting content!"
echo "***************************************************************************************"
echo ""
find . -name 'master.adoc' -print | xargs sed -i "s/include::$CURRENT_GUIDE\//include::/g"
# Remove the html and build directories and then recreate the html/images/ directory
if [ -d target/html ]; then
rm -r target/html/
fi
if [ -d target/html ]; then
rm -r target/html/
fi
mkdir -p html
cp -r target/images/ target/html/
echo "Building an asciidoctor version of the guide"
asciidoctor -t -dbook -a toc -o target/html/$CURRENT_GUIDE.html target/master.adoc
echo ""
echo "Building a ccutil version of the guide"
ccutil compile --lang en_US --format html-single --main-file target/master.adoc
cd ..
echo "View the asciidoctor build here: " file://$CURRENT_DIRECTORY/target/html/$CURRENT_GUIDE.html
if [ -d $CURRENT_DIRECTORY/build/tmp/en-US/html-single/ ]; then
echo "View the ccutil build here: " file://$CURRENT_DIRECTORY/build/tmp/en-US/html-single/index.html
exit 0
else
echo -e "${RED}Build using ccutil failed!"
echo -e "${BLACK}See the log above for details."
exit 1
fi

113
getting_started/gitlab-conversion.py
View file

@ -1,113 +0,0 @@
import sys, os, re, json, shutil, errno
def transform(root, f, targetdir):
full = os.path.join(root, f)
input = open(full, 'r').read()
dir = os.path.join(targetdir, root)
if not os.path.exists(dir):
os.makedirs(dir)
output = open(os.path.join(dir, f), 'w')
input = applyTransformation(input)
output.write(input)
def applyTransformation(input):
for variable in re.findall(r"\{\{(.*?)\}\}", input):
tmp = variable.replace('.', '_')
input = input.replace(variable, tmp)
input = input.replace('{{', '{').replace('}}', '}')
input = re.sub(r"<<fake.+#", "<<", input)
for variable in re.findall(r"[ ]*{% if (.*?) %}", input):
tmp = variable.replace('.', '_')
input = input.replace(variable, tmp)
exp = re.compile("[ ]*{% if (.*?) %}(.*?)[ ]*{% endif %}", re.DOTALL)
input = re.sub(exp, "ifeval::[{\g<1>}==true]\g<2>endif::[]", input)
input = re.sub(r"image:(\.\./)*", "image:", input)
input = re.sub(r"image::(\.\./)*", "image::", input)
return input
indir = 'topics'
targetdir = 'target'
if len(sys.argv) > 1:
targetdir = sys.argv[1]
if os.path.exists(targetdir):
shutil.rmtree(targetdir)
if os.path.isdir('images'):
shutil.copytree('images',os.path.join(targetdir, 'images'))
if os.path.isdir('keycloak-images'):
shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images'))
if os.path.isdir('rhsso-images'):
shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images'))
shutil.copyfile('metadata.ini', os.path.join(targetdir, 'metadata.ini'));
shutil.copyfile('master-docinfo.xml', os.path.join(targetdir, 'master-docinfo.xml'));
tmp = os.path.join(targetdir, 'topics')
if not os.path.exists(tmp):
os.makedirs(tmp)
# transform files
for root, dirs, filenames in os.walk(indir):
for f in filenames:
transform(root,f,targetdir)
# Create master.doc includes
input = open('SUMMARY.adoc', 'r').read()
output = open(os.path.join(targetdir, 'master.adoc'), 'w')
output.write("""
:toc:
:toclevels: 3
:numbered:
include::document-attributes.adoc[]
""")
input = re.sub(r"[ ]*\.+\s*link:[^/]+/(.*)\[(.*)\]", "include::\g<1>[]", input)
input = applyTransformation(input)
output.write(input)
# parse book-product.json file and create document attributes
with open('book-product.json') as data_file:
data = json.load(data_file)
variables = data['variables']
def makeAttributes(variables, variable, list):
for i in variables.keys():
if variable is None:
tmp = i
else:
tmp = variable + '_' + i
if isinstance(variables[i],dict):
makeAttributes(variables[i], tmp, list)
elif isinstance(variables[i],bool):
boolval = 'false'
if variables[i]:
boolval = 'true'
list.append({tmp: boolval})
else:
list.append({tmp: str(variables[i])})
attributeList = []
makeAttributes(variables, None, attributeList)
output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w')
for attribute in attributeList:
for k in attribute.keys():
output.write(':book_' + k + ": " + attribute[k] + "\n")
print "Transformation complete!"

6
getting_started/index.adoc Normal file
View file

@ -0,0 +1,6 @@
:toc:
:toclevels: 3
:numbered:
include::../document-attributes-community.adoc[]
include::topics.adoc[]

12
getting_started/master-docinfo.xml
View file

@ -1,10 +1,10 @@
<productname>{book_project_name}</productname>
<productnumber>{book_project_doc_info_version_url}</productnumber>
<subtitle>For Use with {book_project_name} {book_project_doc_info_version_url}</subtitle>
<title>{book_title}</title>
<release>{book_project_doc_info_version_url}</release>
<productname>{project_name}</productname>
<productnumber>{project_doc_info_version_url}</productnumber>
<subtitle>For Use with {project_name} {project_doc_info_version_url}</subtitle>
<title>{title}</title>
<release>{project_doc_info_version_url}</release>
<abstract>
<para>This guide consists of basic information and instructions to get started with {book_project_name} {book_project_doc_info_version_url}</para>
<para>This guide consists of basic information and instructions to get started with {project_name} {project_doc_info_version_url}</para>
</abstract>
<authorgroup>
<orgname>Red Hat Customer Content Services</orgname>

6
getting_started/master.adoc Normal file
View file

@ -0,0 +1,6 @@
:toc:
:toclevels: 3
:numbered:
include::../document-attributes-product.adoc[]
include::topics.adoc[]

29
getting_started/pom.xml Normal file
View file

@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.keycloak.documentation</groupId>
<artifactId>documentation-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../</relativePath>
</parent>
<name>Getting Started</name>
<artifactId>getting-started</artifactId>
<packaging>pom</packaging>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<executions>
<execution>
<id>asciidoc-to-html</id>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

22
getting_started/topics.adoc Normal file
View file

@ -0,0 +1,22 @@
include::topics/overview.adoc[]
include::topics/first-boot.adoc[]
ifeval::[{project_community}==true]
include::topics/first-boot/distribution-files-community.adoc[]
endif::[]
ifeval::[{project_product}==true]
include::topics/first-boot/distribution-files-product.adoc[]
endif::[]
include::topics/first-boot/boot.adoc[]
include::topics/first-boot/initial-user.adoc[]
include::topics/first-boot/admin-console.adoc[]
include::topics/first-realm.adoc[]
include::topics/first-realm/before.adoc[]
include::topics/first-realm/realm.adoc[]
include::topics/first-realm/user.adoc[]
include::topics/first-realm/account.adoc[]
include::topics/secure-jboss-app.adoc[]
include::topics/secure-jboss-app/before.adoc[]
include::topics/secure-jboss-app/install-client-adapter.adoc[]
include::topics/secure-jboss-app/download-quickstarts.adoc[]
include::topics/secure-jboss-app/create-client.adoc[]
include::topics/secure-jboss-app/subsystem.adoc[]

2
getting_started/topics/first-boot.adoc Executable file → Normal file
View file

@ -3,5 +3,5 @@
== Installing and Booting
This very short tutorial walks you through booting up the server in standalone mode, setting up the initial admin user,
and logging into the {{book.project.name}} admin console.
and logging into the {project_name} admin console.

6
getting_started/topics/first-boot/admin-console.adoc Executable file → Normal file
View file

@ -7,12 +7,12 @@ After you create the initial admin account, you can log in to the Admin Console
Alternatively you can go to the console URL directly at http://localhost:8080/auth/admin/
+
.Login Page
image:../../{{book.images}}/login-page.png[]
image:{project_images}/login-page.png[]
. Type the username and password you created on the Welcome page. The {{book.project.name}} Admin Console page opens.
. Type the username and password you created on the Welcome page. The {project_name} Admin Console page opens.
+
.Admin Console
image:../../{{book.images}}/admin-console.png[]
image:{project_images}/admin-console.png[]
NOTE: If you are curious about a certain feature, button, or field within the Admin Console, hover your mouse
over the question mark `?` icon. This will pop up tooltip text to describe the area of the console you are interested in.

4
getting_started/topics/first-boot/boot.adoc Executable file → Normal file
View file

@ -1,10 +1,10 @@
=== Booting the Server
To boot the {{book.project.name}} server, go to the _bin/_ directory of the server distribution.
To boot the {project_name} server, go to the _bin/_ directory of the server distribution.
.Standalone Boot Scripts
image:../../{{book.images}}/standalone-boot-files.png[]
image:{project_images}/standalone-boot-files.png[]
To boot the server:

8
getting_started/topics/first-boot/distribution-files-community.adoc Executable file → Normal file
View file

@ -1,12 +1,12 @@
=== Installing Distribution Files
The {{book.project.name}} Server is contained in one distribution file:
The {project_name} Server is contained in one distribution file:
* 'keycloak-{{book.project.version}}.[zip|tar.gz]'
* 'keycloak-{project_version}.[zip|tar.gz]'
The 'keycloak-{{book.project.version}}.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries
to run the {{book.project.name}} server.
The 'keycloak-{project_version}.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries
to run the {project_name} server.
To unpack these files run the `unzip` or `gunzip` and `tar` utilities.

8
getting_started/topics/first-boot/distribution-files-product.adoc Executable file → Normal file
View file

@ -1,12 +1,12 @@
=== Installing the Server
The {{book.project.name}} Server is contained in one distribution file:
The {project_name} Server is contained in one distribution file:
* 'RH-SSO-{{book.project.version}}.[zip|tar.gz]'
* 'RH-SSO-{project_version}.[zip|tar.gz]'
The 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' file is the server-only distribution. It contains only the scripts and binaries
to run the {{book.project.name}} server.
The 'RH-SSO-{project_version}.[zip|tar.gz]' file is the server-only distribution. It contains only the scripts and binaries
to run the {project_name} server.
To unpack these files run the `unzip` or `gunzip` and `tar` utilities.

8
getting_started/topics/first-boot/initial-user.adoc Executable file → Normal file
View file

@ -4,14 +4,14 @@
After the server boots, open your browser and go to the http://localhost:8080/auth URL. The page should look like this:
.Welcome Page
image:../../{{book.images}}/initial-welcome-page.png[]
image:{project_images}/initial-welcome-page.png[]
{{book.project.name}} does not have a configured admin account by default. You must create one on the Welcome page.
{project_name} does not have a configured admin account by default. You must create one on the Welcome page.
This account will allow you to create an admin that can log into the _master_ realm's administration console so that
you can start creating realms and users and registering applications to be secured by {{book.project.name}}.
you can start creating realms and users and registering applications to be secured by {project_name}.
NOTE: You can only create an initial admin user on the Welcome Page if you connect using `localhost`. This is a security
precaution. You can also create the initial admin user at the command line with the `add-user-keycloak.sh` script. For more details see
link:{{book.installguide.link}}[{{book.installguide.name}}] and link:{{book.adminguide.link}}[{{book.adminguide.name}}].
link:{installguide_link}[{installguide_name}] and link:{adminguide_link}[{adminguide_name}].

2
getting_started/topics/first-realm.adoc Executable file → Normal file
View file

@ -1,6 +1,6 @@
== Creating a Realm and User
This short tutorial walks you through creating a new realm within the {{book.project.name}} Admin Console and adding
This short tutorial walks you through creating a new realm within the {project_name} Admin Console and adding
a new user to that realm. With that new user you will log into your new realm and visit the built-in User Account
service that all users have access to.

4
getting_started/topics/first-realm/account.adoc Executable file → Normal file
View file

@ -11,10 +11,10 @@ User Account Link::
. Type the username and password you created previously. You must create a permanent password after you successfully log in if you didn't toggle the Temporary switch to *Off* previously.
+
.Update Password
image:../../{{book.images}}/update-password.png[]
image:{project_images}/update-password.png[]
The User Account Service page opens. Every user in a realm has access to this Account Service by default.
You can update profile information and change or add additional credentials. For more information on this service see the link:{{book.adminguide.link}}[{{book.adminguide.name}}].
You can update profile information and change or add additional credentials. For more information on this service see the link:{adminguide_link}[{adminguide_name}].

4
getting_started/topics/first-realm/before.adoc Executable file → Normal file
View file

@ -1,6 +1,6 @@
=== Before You Start
Before you can participate in this tutorial, you need to complete the installation of {{book.project.name}} and create the
initial admin user as shown in the <<fake/../../first-boot.adoc#_install-boot, Installing and Booting>> tutorial.
Before you can participate in this tutorial, you need to complete the installation of {project_name} and create the
initial admin user as shown in the <<_install-boot, Installing and Booting>> tutorial.

8
getting_started/topics/first-realm/realm.adoc Executable file → Normal file
View file

@ -4,8 +4,8 @@
To create a new realm, complete the following steps:
. Log in to the {{book.project.name}} Admin Console using the account you created in the
<<fake/../../first-boot.adoc#_install-boot, Install and Boot>> tutorial.
. Log in to the {project_name} Admin Console using the account you created in the
<<_install-boot, Install and Boot>> tutorial.
Admin Console Link::
http://localhost:8080/auth/admin/
@ -13,13 +13,13 @@ Admin Console Link::
. In the top left corner dropdown menu that is titled `Master`, click *Add Realm*. If you are logged in to the master realm this dropdown menu lists all the realms created. The Add Realm page opens.
+
.Add Realm Menu
image:../../{{book.images}}/add-realm-menu.png[]
image:{project_images}/add-realm-menu.png[]
. You will be creating a brand new realm from scratch so
type `demo` for the realm name and click `Create`.
+
.Create Realm
image:../../{{book.images}}/create-realm.png[]
image:{project_images}/create-realm.png[]
After creating the realm the main Admin Console page opens. The current realm is now set to `demo`. You can switch between managing the `master` realm and the realm you just created by clicking the top left corner dropdown menu.

6
getting_started/topics/first-realm/user.adoc Executable file → Normal file
View file

@ -7,20 +7,20 @@ To create a new user in the `demo` realm as well as a temporary password for tha
. In the left menu bar click *Users*. The user list page opens.
+
.Users
image:../../{{book.images}}/users.png[]
image:{project_images}/users.png[]
. On the right side of the empty user list, click *Add User*.
+
.Add User
image:../../{{book.images}}/add-user.png[]
image:{project_images}/add-user.png[]
. The only required field is `Username`. When you are finished, click *Save*. The management page for your new user opens.
. The next step is to define a temporary password for your new user. Click the *Credentials* tab.
+
.Set Temporary Password
image:../../{{book.images}}/credentials.png[]
image:{project_images}/credentials.png[]
. Type a new password and confirm it. A red *Reset Password* button is displayed.
. Click *Reset Password* to reset the user password to the new one you specified.

Some files were not shown because too many files have changed in this diff Show more