From e22a439e594bda17d04c2623512ad6f7584b2b24 Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Tue, 20 Sep 2016 11:29:46 +0200 Subject: [PATCH] Added bits for productized version of docs --- README.adoc | 9 ++- README.md | 1 - book-product.json | 22 ++++++ book.json | 2 +- build.sh | 7 ++ gitlab-conversion.py | 113 +++++++++++++++++++++++++++++++ master-docinfo.xml | 12 ++++ metadata.ini | 20 ++++++ topics/overview/overview.adoc | 7 ++ topics/overview/terminology.adoc | 14 ++-- 10 files changed, 193 insertions(+), 14 deletions(-) delete mode 100644 README.md create mode 100755 book-product.json create mode 100755 build.sh create mode 100755 gitlab-conversion.py create mode 100755 master-docinfo.xml create mode 100644 metadata.ini diff --git a/README.adoc b/README.adoc index 03484e99f5..21d442a54d 100755 --- a/README.adoc +++ b/README.adoc @@ -1,9 +1,8 @@ -Keycloak Authorization Services Guide -====================== + += Authorization Services Guide image:images/keycloak_logo.png[alt="Keycloak"] -*Keycloak* _Documentation_ for {{book.project.version}} - -http://www.keycloak.org +{{book.project.name}} {{book.project.version}} +http://www.keycloak.org \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index 6930beeef0..0000000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -# authorization_services_guide \ No newline at end of file diff --git a/book-product.json b/book-product.json new file mode 100755 index 0000000000..b9d4b6614d --- /dev/null +++ b/book-product.json @@ -0,0 +1,22 @@ +{ + "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", + "project": { + "name": "Red Hat Single Sign-On", + "version": "7.0.0", + "module": "Authorization Services" + } + } +} diff --git a/book.json b/book.json index 97a21a66f7..cfbed953dc 100755 --- a/book.json +++ b/book.json @@ -9,7 +9,7 @@ "splitter" ], "variables": { - "title": "Keycloak Authorization Services Guide", + "title": "Authorization Services Guide", "community": true, "product": false, "images": "keycloak-images", diff --git a/build.sh b/build.sh new file mode 100755 index 0000000000..fc1e19f7fb --- /dev/null +++ b/build.sh @@ -0,0 +1,7 @@ +#!/bin/bash + +cd $(readlink -f `dirname $0`) + +python gitlab-conversion.py +cd target +asciidoctor master.adoc diff --git a/gitlab-conversion.py b/gitlab-conversion.py new file mode 100755 index 0000000000..9144f04d72 --- /dev/null +++ b/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"<}==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!" + + + + + + + + + diff --git a/master-docinfo.xml b/master-docinfo.xml new file mode 100755 index 0000000000..593cce7978 --- /dev/null +++ b/master-docinfo.xml @@ -0,0 +1,12 @@ +Red Hat Single Sign-On +7.0 +Authorization Services Guide +Authorization Services Guide +7.0 + + This guide consist of information for authorization services for Red Hat Single Sign-On 7.0 + + + Red Hat Customer Content Services + + diff --git a/metadata.ini b/metadata.ini new file mode 100644 index 0000000000..cb26fefb1f --- /dev/null +++ b/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 + diff --git a/topics/overview/overview.adoc b/topics/overview/overview.adoc index 50539306bd..ed31fbc719 100755 --- a/topics/overview/overview.adoc +++ b/topics/overview/overview.adoc @@ -1,5 +1,12 @@ == Overview +{% if book.product %} +{{book.project.module}} is a Technology Preview feature and is not fully supported. The feature is disabled by default. + +To enable {{book.project.module}} edit `standalone/configuration/profile.properties` (or `domain/configuration/profile.properties`) +and set `profile=preview` to enable preview features. +{% endif %} + {{book.project.name}} supports fine-grained authorization policies and is able to mix and match different access control mechanisms such as: diff --git a/topics/overview/terminology.adoc b/topics/overview/terminology.adoc index c563fb4614..e7cefd9ce4 100755 --- a/topics/overview/terminology.adoc +++ b/topics/overview/terminology.adoc @@ -2,7 +2,7 @@ Before going further, it is important to understand some terms and concepts introduced by {{book.project.name}} {{book.project.module}}. -==== Resource Server +=== Resource Server Per OAuth2 terminology, a Resource Server is the server hosting the protected resources and capable of accepting and responding to protected resource requests. @@ -13,7 +13,7 @@ authenticate their users usually store that information in the user's session an In Keycloak, any *confidential* client application may act as a resource server. This client's resources and their respective scopes are protected and ruled by a set of authorization policies. -==== Resource +=== Resource A resource is part of the assets of an application and the organization. It can be a set of one or more endpoints, a classic web resource such as an HTML page, and so on. In authorization policy terminology, a resource is the _object_ being protected. @@ -21,7 +21,7 @@ In authorization policy terminology, a resource is the _object_ being protected. Every single resource has a unique identifier which may represent a single resource or a set of resources. For instance, you may want to manage a _Banking Account Resource_ that represents and defines a set of authorization policies for all banking accounts. But you may also have a different resource named _Alice's Banking Account_, which represents a single resource owned by a single customer, which may have its own set of authorization policies. -==== Scope +=== Scope A resource's scope is a bounded extent of access that is possible to perform on a resource. In authorization policy terminology, a scope is one of the potentially many _verbs_ that can logically apply to a resource. @@ -31,7 +31,7 @@ _edit_, _delete_, etc. However, it may also be related with some information pro may have a _Project_ resource and a _cost_ scope, where _cost_ scope may be used to define specific policies and permissions for those trying to access project's cost. -==== Permission +=== Permission Consider this simple and very common permission: @@ -49,7 +49,7 @@ A permission associates the object being protected with the policies that must b * Support a more flexible security model, helping you to easily adapt to changes in your security requirements * Make changes at runtime -- applications only care about the resources and scopes being protected and not how they are actually protected -==== Policy +=== Policy A policy defines the conditions that must be satisfied to grant access to an object. Different than permissions, you don't specify the object being protected but the conditions that must be satisfied to get access to a given object (e.g., resource, scope, or both). @@ -60,7 +60,7 @@ Keycloak leverages the concept of policies and how you define them by providing Instead of writing a single and huge policy with all conditions that must be satisfied to get access to a given resource, the policies implementation in {{book.project.name}} {{book.project.module}} follows the *divide-and-conquer* technique. That is, you can create individual policies, reuse them on different permissions, and build more complex policies by combining individual policies. -==== Policy Provider +=== Policy Provider Policy providers are implementations of specific policy types. {{book.project.name}} provides some built-in policies, backed by their corresponding policy providers, and you are free to create your own policy types to support your specific requirements. @@ -68,7 +68,7 @@ policy providers, and you are free to create your own policy types to support yo {{book.project.name}} provides a *SPI* (Service Provider Interface) that you can use to plug in your own policy provider implementations. [[_permission_ticket]] -==== Permission Ticket +=== Permission Ticket A Permission Ticket is a special type of token defined by the https://docs.kantarainitiative.org/uma/rec-uma-core.html[OAuth2's User-Managed Access (UMA) Profile] specification that provides an opaque structure whose form is determined by the authorization server. This structure represents the resources and/or scopes being requested by a client as well a the policies that must be applied to a request for authorization data (requesting party token or RPT).