Merge remote-tracking branch 'tmp/master'

authorization_services/README.adoc

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

authorization_services/SUMMARY.adoc

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

authorization_services/book-product.json

@@ -0,0 +1,44 @@
+{
+  "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": "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/red-hat-single-sign-on/",
+      "doc_info_version_url": "7.1-Beta"
+    },
+    "external_link": {
+      "keycloakjsadapter": {
+        "name": "JavaScript OpenID Connect Adapter",
+        "link": "/single/securing-applications-and-services-guide#javascript_adapter"
+      },
+      "keycloakgettingstarted": {
+        "name": "Getting Started",
+        "link": "/paged/getting-started-guide/"
+      },
+      "keycloakinstallingandboot": {
+        "name": "Installing and Boot",
+        "link": "/single/getting-started-guide/#install-boot"
+      },
+      "keycloakinstallclientadapter": {
+        "name": "Installing the Client Adapter",
+        "link": "/single/getting-started-guide/#installing_the_client_adapter"
+      }
+    }
+  }
+}

authorization_services/book.json

@@ -0,0 +1,44 @@
+{
+  "gitbook": "2.x.x",
+  "structure": {
+    "readme": "README.adoc"
+  },
+  "plugins": [
+    "toggle-chapters",
+    "ungrey",
+    "splitter"
+  ],
+  "variables": {
+    "title": "Authorization Services Guide",
+    "community": true,
+    "product": false,
+    "images": "keycloak-images",
+    "appServer": "WildFly 10",
+    "quickstartRepo": "https://github.com/redhat-developer/redhat-sso-quickstarts",
+    "project": {
+      "name": "Keycloak",
+      "version": "SNAPSHOT",
+      "module": "Authorization Services",
+      "doc_base_url": "https://keycloak.gitbooks.io/",
+      "doc_info_version_url": ""
+    },
+    "external_link": {
+      "keycloakjsadapter": {
+        "name": "JavaScript OpenID Connect Adapter",
+        "link": "/securing-client-applications-guide/content/topics/oidc/javascript-adapter.html"
+      },
+      "keycloakgettingstarted": {
+        "name": "Getting Started",
+        "link": "/getting-started-tutorials/content/"
+      },
+      "keycloakinstallingandboot": {
+        "name": "Installing and Boot",
+        "link": "/getting-started-tutorials/content/topics/first-boot.html"
+      },
+      "keycloakinstallclientadapter": {
+        "name": "Installing the Client Adapter",
+        "link": "/getting-started-tutorials/content/topics/secure-jboss-app/install-client-adapter.html"
+      }
+    }
+  }
+}

authorization_services/build.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+cd $(readlink -f `dirname $0`)
+
+python gitlab-conversion.py
+cd target
+asciidoctor master.adoc

authorization_services/buildGuide.sh

@@ -0,0 +1,69 @@
+# 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
+
+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 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 ""
+echo "********************************************"
+echo " Building $CURRENT_GUIDE                "
+echo "********************************************"
+echo ""
+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

authorization_services/gitlab-conversion.py

@@ -0,0 +1,113 @@
+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!"
+
+
+
+
+
+
+
+
+

authorization_services/internal-resources/README.adoc

@@ -0,0 +1,3 @@
+= Documentation : internal-resources/
+
+The `internal-resources/` directory contains internal reference documentation written for use by the documentation team.

authorization_services/internal-resources/template_concept.adoc

@@ -0,0 +1,17 @@
+[[concept_module]]
+
+= Concept Template and Guidelines
+
+_In the title, include nouns that are used in the body text -- this helps readers and search engines find information quickly._
+
+A concept module describes and explains things such as a product, subsystem, or feature -- what a customer needs to understand to do a task. A concept module may also explain how things relate and interact with other things. The use of graphics and diagrams can speed up understanding of a concept.
+
+* Look at nouns and noun phrases in related task modules and user story assemblies to find the concepts to explain to users. 
+
+* A concept module in product documentation should explain only things that are visible to users. 
+
+* If a product concept is interesting, but not visible to users, the concept probably does not require explanation in a concept module. 
+
+* A concept module should NOT include numbered steps or other wording that instructs a user to execute a command or perform an action. Instead, put that information in a separate task module or user story assembly.
+
+

authorization_services/internal-resources/template_reference.adoc

@@ -0,0 +1,13 @@
+[[reference_module]]
+
+= Reference Template and Guidelines
+
+_In the title, include nouns that are used in the body text — this helps readers and search engines find information quickly._
+
+A reference module lists things (such as a list of commands) or has a very regimented structure (such as the consistent structure of man pages). A reference module explains the details that a customer needs to know to do a task.  A reference module is well-organized if users can scan it to quickly find the details they want.
+
+* A reference module that is a list of things may be made easier to scan if its content is organized alphabetically or formatted as a table. Think of an alphabetical list of commands that can be used with an application, or of an alphabetical list of system components with brief definitions formatted as a 2-column table.
+
+* If you have a large volume of the same type of information to document, figure out a consistent structure that the information details can fit into and then doument each logical unit of information as 1 reference module. Think of man pages, which document very different information details, but that use consistent titles and formats to present those details in a consistent information structure.
+
+

authorization_services/internal-resources/template_task.adoc

@@ -0,0 +1,59 @@
+[[task_module]]
+
+= Do One Task
+
+_Start title with verb form such as Creating. Use the gerund form (noun form of verb) for titles, not the imperative form._
+
+_Avoid using the word 'Configuring' over and over.  Other words might include:_
+
+* _Specifying_
+* _Adding_
+* _Constructing_
+* _Arranging_
+* _Building_
+* _Setting_
+* _Managing_
+* _Defining_
+* _Customizing_
+* _Or instead of using synonyms (which becomes obvious) 'verb-alize' a word and refactor the heading - limiting (instead of 'setting resource limits')_
+
+_The standard for all Red Hat documentation is title case for all headings and titles._
+
+_A task module is a procedure written with numbered steps -- what a customer needs to do to accomplish a goal successfully._
+
+This paragraph explains why the user performs the task, sets the context of the task, and may explain or list special considerations specific to this task. Keep the information brief and focused on what is needed for this specific task. Suggested length is 1 to 3 sentences, can be longer if needed.
+
+
+.Prerequisites _(if needed)_
+
+* Sentence or a bulleted list of prerequisites that must be in place or done before the user starts this task. 
+
+* Delete section title and bullets if the task has no required prerequisites.
+
+* Text can be a link to a prerequisite task that the user must do before starting this task.
+
+
+.Procedure
+
+_Start title with verb form such as Creating. Use the gerund form (noun form of verb) for titles, not the imperative form._
+
+_Put steps in a numbered list. The step sequence is important to a repeatable successful outcome._
+
+. Start each step with an active verb, because each step corresponds to one user action.
+
+. Include one command or action per step.
+
+. Format the step line as an unnumbered bullet if the procedure includes only 1 step (exception to numbering the steps).
+
+. Include one command or action per step.
+
+. Include one command or action per step.
+
+
+.Related Information _(if needed)_
+
+* Bulleted list of links to concepts, reference, or other tasks closely related to this task. 
+
+* Include only the most relevant items as links, not every possible related item.
+
+* Delete section title and bullets if no related information is needed.

authorization_services/internal-resources/template_task_brief.adoc

@@ -0,0 +1,20 @@
+[[task_module]]
+
+= Do One Task
+
+This paragraph explains why the user performs the task, sets the context of the task, and may explain or list special considerations specific to this task. Keep the information brief and focused on what is needed for this specific task. Suggested length is 1 to 3 sentences, can be longer if needed.
+
+
+.Prerequisites _(if needed)_
+
+* List
+
+
+.Procedure
+
+. List
+
+
+.Related Information _(if needed)_
+
+* List

authorization_services/master-docinfo.xml

@@ -0,0 +1,12 @@
+<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>{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>
+    </abstract>
+<authorgroup>
+    <orgname>Red Hat Customer Content Services</orgname>
+</authorgroup>
+<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

authorization_services/metadata.ini

@@ -0,0 +1,20 @@
+[source]
+language = en-US
+type = book
+markup = asciidoc
+
+[metadata]
+title = Authorization Services Guide
+product = Red Hat Single Sign-On
+version = 7.0
+edition = 
+subtitle = 
+keywords = 
+abstract = 
+
+[bugs]
+reporting_url = 
+type = 
+product = 
+component = Documentation
+