Apply to Keycloak documentation style to the Getting Started guides (#17173)
Closes #17133
This commit is contained in:
andymunro
GitHub
parent
1d75000a0e
commit
b8e01596f6
11 changed files with 114 additions and 114 deletions
|
|
@ -11,37 +11,37 @@ summary="Get started with Keycloak on Kubernetes">
|
|||
|
||||
Make sure you have Minikube installed, ideally with the Ingress addon enabled.
|
||||
|
||||
To check if you have the Ingress addon enabled run:
|
||||
To check if you have the Ingress addon enabled, enter the following command:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
minikube addons list
|
||||
----
|
||||
|
||||
If the Ingress addon is not enabled run the following to enable it:
|
||||
If the Ingress addon is not enabled, enter the following command to enable it:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
minikube addons enable ingress
|
||||
----
|
||||
|
||||
== Run Keycloak
|
||||
== Start Keycloak
|
||||
|
||||
The Keycloak QuickStarts repository includes some example files to help deploy Keycloak to Kubernetes.
|
||||
|
||||
Let's start with creating the Keycloak deployment and service:
|
||||
As a first step, create the Keycloak deployment and service by entering the following command:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/kubernetes-examples/keycloak.yaml
|
||||
----
|
||||
|
||||
This will start Keycloak on Kubernetes. It will also create an initial admin user with username `admin` and password
|
||||
This command starts Keycloak on Kubernetes and creates an initial admin user with the username `admin` and password
|
||||
`admin`.
|
||||
|
||||
=== Access Keycloak with Ingress addon enabled
|
||||
|
||||
Start by creating an Ingress for Keycloak:
|
||||
Now create an Ingress for Keycloak by entering the following command:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
|
|
@ -50,10 +50,10 @@ sed "s/KEYCLOAK_HOST/keycloak.$(minikube ip).nip.io/" | \
|
|||
kubectl create -f -
|
||||
----
|
||||
|
||||
If you don't have `wget` and `sed` available, download the file and manually edit the file replacing `KEYCLOAK_HOST`
|
||||
If `wget` and `sed` are not available, download the file and manually edit the file replacing `KEYCLOAK_HOST`
|
||||
with `keycloak.<minikube ip address>.nip.io`.
|
||||
|
||||
Run the following to find out the URLs of Keycloak:
|
||||
Enter the following command to see the Keycloak URLs:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
|
|
@ -65,19 +65,16 @@ echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
|
|||
echo ""
|
||||
----
|
||||
|
||||
Remember these URLs as you will need them throughout this guide. The URL for the account console won't work
|
||||
right now as you will need to create the realm first.
|
||||
|
||||
=== Access Keycloak without Ingress
|
||||
|
||||
If you don't have the Ingress addon enabled, first run in a separate shell:
|
||||
If the Ingress addon is not enabled, enter the following command in a separate shell:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
minikube tunnel
|
||||
----
|
||||
|
||||
and you can now access Keycloak from the following URL:
|
||||
You can now access Keycloak from the following URL:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
|
|
@ -89,8 +86,7 @@ echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
|
|||
echo ""
|
||||
----
|
||||
|
||||
Remember these URLs as you will need them throughout this guide. The URL for the account console won't work
|
||||
right now as you will need to create the realm first.
|
||||
Remember these URLs. You need them as you follow the instructions in this guide. The URL for the Account Console does not work yet as you need to create the realm first.
|
||||
|
||||
include::templates/realm-config.adoc[]
|
||||
|
||||
|
|
|
|||
|
|
@ -9,18 +9,18 @@ summary="Get started with Keycloak on OpenShift">
|
|||
|
||||
== Before you start
|
||||
|
||||
Install https://code-ready.github.io/crc/[Red Hat Code Ready Containers] and follow the steps in the documentation to install a
|
||||
. Install https://code-ready.github.io/crc/[Red Hat Code Ready Containers] and follow the steps in the documentation to install a
|
||||
local OpenShift cluster.
|
||||
|
||||
Make sure the cluster is functional by executing the following command:
|
||||
|
||||
. Make sure the cluster is functional by entering the following command:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
crc status
|
||||
----
|
||||
|
||||
If everything is OK you should see an output similar to this:
|
||||
|
||||
. Look for output similar to the following to confirm the cluster is working.
|
||||
+
|
||||
[source,subs="attributes+"]
|
||||
----
|
||||
CRC VM: Running
|
||||
|
|
@ -28,24 +28,24 @@ OpenShift: Running
|
|||
...
|
||||
----
|
||||
|
||||
Log in as the user `developer`:
|
||||
|
||||
. Log in as the user `developer`:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
oc login -u developer -p developer
|
||||
----
|
||||
|
||||
For this guide, we are going to create a new project called `keycloak`. For that, execute the following command:
|
||||
|
||||
. Create a project called `keycloak` by entering the following command:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
oc new-project keycloak
|
||||
----
|
||||
|
||||
== Run Keycloak
|
||||
|
||||
To spin up a Keycloak server in your project, execute the following command:
|
||||
== Start Keycloak
|
||||
|
||||
. To start a Keycloak server in your project, enter the following command:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
oc process -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/openshift-examples/keycloak.yaml \
|
||||
|
|
@ -55,27 +55,27 @@ oc process -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/la
|
|||
| oc create -f -
|
||||
----
|
||||
|
||||
Once the command above completes you should see a message similar to this:
|
||||
|
||||
. Once the command above completes, look for a message similar to this:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
service/keycloak created
|
||||
route.route.openshift.io/keycloak created
|
||||
deploymentconfig.apps.openshift.io/keycloak created.
|
||||
----
|
||||
+
|
||||
At this point, OpenShift will provision a Keycloak pod and related resources. As part of the process, OpenShift will
|
||||
try to pull the Keycloak server image. This operation might take some time depending on your network connection.
|
||||
|
||||
At this point, OpenShift is going to provision a Keycloak pod and related resources. As part of the process, OpenShift will
|
||||
try to pull the Keycloak server image. This might take some time depending on your network connection.
|
||||
|
||||
To make sure Keycloak is provisioned, execute the following command:
|
||||
|
||||
. To make sure Keycloak is provisioned, execute the following command:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
oc get pods
|
||||
----
|
||||
|
||||
After a while you will see a message similar to this when the pod is ready:
|
||||
|
||||
. After a while, look for a message similar to the following; it indicates the pod is ready:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
|
|
@ -83,8 +83,8 @@ keycloak-1-deploy 0/1 Completed 0 1h
|
|||
keycloak-1-l9kdx 1/1 Running 0 1h
|
||||
----
|
||||
|
||||
Once the server is provisioned, run the following command to find out the URLs of Keycloak:
|
||||
|
||||
. Once the server is provisioned, enter the following command to find out the Keycloak URLs:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') &&
|
||||
|
|
|
|||
|
|
@ -10,14 +10,14 @@ summary="Get started with Keycloak on bare metal">
|
|||
|
||||
== Before you start
|
||||
|
||||
Make sure you have https://openjdk.java.net/[OpenJDK 11] or newer installed.
|
||||
Make sure you have https://openjdk.java.net/[OpenJDK 11] or a higher version installed.
|
||||
|
||||
== Download Keycloak
|
||||
|
||||
First step is to download and extract https://github.com/keycloak/keycloak/releases/download/{version}/keycloak-{version}.zip[keycloak-{version}.zip]
|
||||
Download and extract https://github.com/keycloak/keycloak/releases/download/{version}/keycloak-{version}.zip[keycloak-{version}.zip]
|
||||
from the Keycloak website.
|
||||
|
||||
After extracting you should have a directory named keycloak-{version}.
|
||||
After extracting this file, you should have a directory named keycloak-{version}.
|
||||
|
||||
include::templates/start-keycloak-localhost.adoc[]
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
== Create an admin user
|
||||
|
||||
Keycloak does not come with a default admin user, which means before you can start using Keycloak you need to create
|
||||
an admin user.
|
||||
Keycloak has no default admin user. You need to create an admin user before you can start Keycloak.
|
||||
|
||||
To do this open http://localhost:8080/[http://localhost:8080/], then fill in the form with your preferred username and password.
|
||||
. Open http://localhost:8080/[http://localhost:8080/].
|
||||
. Fill in the form with your preferred username and password.
|
||||
|
|
|
|||
|
|
@ -1,36 +1,39 @@
|
|||
== Secure your first app
|
||||
== Secure the first application
|
||||
|
||||
Let's try to secure our first application. First step is to register this application with your Keycloak instance:
|
||||
To secure the first application, you start by registering the application with your Keycloak instance:
|
||||
|
||||
. Open the {links-admin-console}
|
||||
. Click 'Clients'
|
||||
. Click 'Create client'
|
||||
. Open the {links-admin-console}.
|
||||
. Click *Clients*.
|
||||
. Click *Create client*
|
||||
. Fill in the form with the following values:
|
||||
** Client type: `OpenID Connect`
|
||||
** Client ID: `myclient`
|
||||
. Click 'Next'
|
||||
. Make sure 'Standard flow' is enabled
|
||||
. Click 'Save'
|
||||
** *Client type*: `OpenID Connect`
|
||||
** *Client ID*: `myclient`
|
||||
. Click *Next*
|
||||
. Confirm that *Standard flow* is enabled.
|
||||
. Click *Save*.
|
||||
|
||||
image::add-client-1.png[Add Client]
|
||||
|
||||
After the client is created you need to update the following values for the client:
|
||||
After the client is created, make these updates to the client:
|
||||
|
||||
. Valid redirect URIs: `https://www.keycloak.org/app/*`
|
||||
. Web origins: `https://www.keycloak.org`
|
||||
|
||||
Remember to click `Save`.
|
||||
. Scroll down to *Access settings*.
|
||||
* Set *Valid redirect URIs* to `+https://www.keycloak.org/app/*+`
|
||||
* Set *Web origins* to `+https://www.keycloak.org+`
|
||||
. Click *Save*.
|
||||
|
||||
image::add-client-2.png[Update Client]
|
||||
|
||||
To make it easy for you we have a SPA testing application available on the https://www.keycloak.org/app/[Keycloak website].
|
||||
To confirm the client was created successfully, you can use the SPA testing application on the https://www.keycloak.org/app/[Keycloak website].
|
||||
|
||||
ifeval::[{links-local}==true]
|
||||
Open https://www.keycloak.org/app/ and click `Save` to use the default configuration.
|
||||
. Open https://www.keycloak.org/app/.
|
||||
. Click *Save* to use the default configuration.
|
||||
endif::[]
|
||||
|
||||
ifeval::[{links-local}!=true]
|
||||
Open https://www.keycloak.org/app/. Change `Keycloak URL` to the URL of your Keycloak instance. Click `Save`.
|
||||
. Open https://www.keycloak.org/app/.
|
||||
. Change `Keycloak URL` to the URL of your Keycloak instance.
|
||||
. Click *Save*.
|
||||
endif::[]
|
||||
|
||||
Now you can click `Sign in` to authenticate to this application using the Keycloak server you started earlier.
|
||||
. Click *Sign in* to authenticate to this application using the Keycloak server you started earlier.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
== Login to account console
|
||||
== Log in to the Account Console
|
||||
|
||||
Let's now try to login to the account console to verify the user is configured correctly.
|
||||
You can now log in to the Account Console to verify this user is configured correctly.
|
||||
|
||||
. Open the {links-account-console}
|
||||
. Login with `myuser` and the password you created earlier
|
||||
. Open the {links-account-console}.
|
||||
. Log in with `myuser` and the password you created earlier.
|
||||
|
||||
You should now be logged-in to the account console where users can manage their accounts.
|
||||
As a user in the Account Console, you can manage your account including modifying your profile, adding two-factor authentication, and including identity provider accounts.
|
||||
|
||||
image::account-console.png[Keycloak Account Console]
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
== Next
|
||||
== Taking the next step
|
||||
|
||||
Before you go and run Keycloak in production there are a few more things that you will want to do, including:
|
||||
Before you run Keycloak in production, consider the following actions:
|
||||
|
||||
* Switch to a production ready database such as PostgreSQL
|
||||
* Configure SSL with your own certificates
|
||||
* Switch the admin password to a more secure password
|
||||
* Switch to a production ready database such as PostgreSQL.
|
||||
* Configure SSL with your own certificates.
|
||||
* Switch the admin password to a more secure password.
|
||||
|
||||
For more information check out the https://www.keycloak.org/guides#server[server guides].
|
||||
For more information, see the https://www.keycloak.org/guides#server[server guides].
|
||||
|
|
|
|||
|
|
@ -1,43 +1,41 @@
|
|||
== Login to the admin console
|
||||
== Log in to the Admin Console
|
||||
|
||||
Go to the {links-admin-console} and login with the username and password
|
||||
you created earlier.
|
||||
. Go to the {links-admin-console}.
|
||||
. Log in with the username and password you created earlier.
|
||||
|
||||
== Create a realm
|
||||
|
||||
A realm in Keycloak is the equivalent of a tenant. It allows creating isolated groups of applications and users. By default
|
||||
there is a single realm in Keycloak called `master`. This is dedicated to manage Keycloak and should not be used for
|
||||
your own applications.
|
||||
A realm in Keycloak is equivalent to a tenant. Each realm allows an administrator to create isolated groups of applications and users. Initially, Keycloak
|
||||
includes a single realm, called `master`. Use this realm only for managing Keycloak and not for managing any applications.
|
||||
|
||||
Let's create our first realm.
|
||||
Use these steps to create the first realm.
|
||||
|
||||
. Open the {links-admin-console}
|
||||
. Hover the mouse over the dropdown in the top-left corner where it says `master`, then click on `Create realm`
|
||||
. Fill in the form with the following values:
|
||||
** Realm name: `myrealm`
|
||||
. Click `Create`
|
||||
. Open the {links-admin-console}.
|
||||
. Click the word *master* in the top-left corner, then click *Create realm*.
|
||||
. Enter `myrealm` in the *Realm name* field.
|
||||
. Click *Create*.
|
||||
|
||||
image::add-realm.png[Add Realm]
|
||||
image::add-realm.png[Add realm]
|
||||
|
||||
== Create a user
|
||||
|
||||
Initially there are no users in a new realm, so let's create one:
|
||||
Initially, the realm has no users. Use these steps to create a user:
|
||||
|
||||
. Open the {links-admin-console}
|
||||
. Click `Users` (left-hand menu)
|
||||
* Click `Create new user` (top-right corner of table)
|
||||
. Open the {links-admin-console}.
|
||||
. Click *Users* in the left-hand menu.
|
||||
. Click *Create new user*.
|
||||
. Fill in the form with the following values:
|
||||
** Username: `myuser`
|
||||
** First Name: Your first name
|
||||
** Last Name: Your last name
|
||||
. Click `Create`
|
||||
** *Username*: `myuser`
|
||||
** *First name*: any first name
|
||||
** *Last name*: any last name
|
||||
. Click *Create*.
|
||||
|
||||
image::add-user.png[Add User]
|
||||
image::add-user.png[Create user]
|
||||
|
||||
The user will need an initial password set to be able to login. To do this:
|
||||
This user needs a password to log in. To set the initial password:
|
||||
|
||||
. Click `Credentials` (top of the page)
|
||||
. Fill in the `Set password` form with a password
|
||||
. Click `ON` next to `Temporary` to prevent having to update password on first login
|
||||
. Click *Credentials* at the top of the page.
|
||||
. Fill in the *Set password* form with a password.
|
||||
. Toggle *Temporary* to *Off* so that the user does not need update this password at the first login.
|
||||
|
||||
image::set-password.png[Set Password]
|
||||
image::set-password.png[Set password]
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
== Start Keycloak
|
||||
|
||||
From a terminal start Keycloak with the following command:
|
||||
From a terminal, enter the following command to start Keycloak:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
{containerCommand} run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:{version} start-dev
|
||||
----
|
||||
|
||||
This will start Keycloak exposed on the local port 8080. It will also create an initial admin user with username `admin`
|
||||
and password `admin`.
|
||||
This command starts Keycloak exposed on the local port 8080 and creates an initial admin user with the username `admin`
|
||||
and password `admin`.
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
== Start Keycloak
|
||||
|
||||
From a terminal open the directory keycloak-{version}, then to start Keycloak run the following command.
|
||||
|
||||
On Linux run:
|
||||
|
||||
. From a terminal, open the keycloak-{version} directory.
|
||||
. Enter the following command:
|
||||
* On Linux, run:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
bin/kc.sh start-dev
|
||||
----
|
||||
|
||||
On Windows run:
|
||||
|
||||
* On Windows, run:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
bin/kc.bat start-dev
|
||||
|
|
|
|||
|
|
@ -1,13 +1,16 @@
|
|||
== Test your setup
|
||||
|
||||
To make it easy for you we have a SPA testing application available on the https://www.keycloak.org/app/[Keycloak website].
|
||||
To confirm the client was created successfully, you can use the SPA testing application on the https://www.keycloak.org/app/[Keycloak website].
|
||||
|
||||
ifeval::[{links-local}==true]
|
||||
Open https://www.keycloak.org/app/ and click `Save` to use the default configuration.
|
||||
. Open https://www.keycloak.org/app/.
|
||||
. Click *Save*` to use the default configuration.
|
||||
endif::[]
|
||||
|
||||
ifeval::[{links-local}!=true]
|
||||
Open https://www.keycloak.org/app/. Change `Keycloak URL` to the URL of your Keycloak instance. Click `Save`.
|
||||
. Open https://www.keycloak.org/app/.
|
||||
. Change `Keycloak URL` to the URL of your Keycloak instance.
|
||||
. Click *Save*.
|
||||
endif::[]
|
||||
|
||||
Now you can click `Sign in` to authenticate to this application using the Keycloak server you started earlier.
|
||||
. Click *Sign in* to authenticate to this application using the Keycloak server you started earlier.
|
||||
Loading…
Reference in a new issue