From 9121667b4b4458bc3dc978524e3be268a35408bf Mon Sep 17 00:00:00 2001 From: jonathan langlois Date: Wed, 22 Nov 2023 15:12:24 -0800 Subject: [PATCH] chore: docs move docs to be compatible with devhub --- README.md | 10 + catalog-info.yaml | 12 + mkdocs.yml | 5 + wiki/Additional-Help.md | 15 + wiki/Alerts-and-Us.md | 242 +++++++++++++ .../Are-you-part-of-the-GitHub-BC-Gov-Org?.md | 14 + wiki/CSS-API-Account.md | 38 ++ wiki/CSS-App-My-Teams.md | 95 +++++ wiki/CSS-App-Valid-Redirect-URI-Format.md | 9 + wiki/Creating-a-Role.md | 69 ++++ ...-Custom-Realm-Community-Ways-of-Working.md | 2 + wiki/Identity-Provider-Attribute-Mapping.md | 12 + wiki/Our-Partners-and-Useful-Information.md | 124 +++++++ wiki/Pathfinder-Uptime-Monitoring.md | 44 +++ ...ogin-Page-and-if-you-ABSOLUTELY-need-it.md | 22 ++ ...to-delete-a-custom-Pathfinder-SSO-Realm.md | 24 ++ wiki/SSO-Onboarding.md | 32 ++ wiki/SSO-Pathfinder-Knowledge-Base.md | 1 + ...ence-Between-Custom-and-Standard-Realms.md | 3 + wiki/Useful-References.md | 80 +++++ wiki/Using-Your-SSO-Client.md | 333 ++++++++++++++++++ wiki/What-is-Keycloak-@-BC-Government?.md | 39 ++ wiki/_Sidebar.md | 18 + wiki/index.md | 118 +++++++ 24 files changed, 1361 insertions(+) create mode 100644 catalog-info.yaml create mode 100644 mkdocs.yml create mode 100644 wiki/Additional-Help.md create mode 100644 wiki/Alerts-and-Us.md create mode 100644 wiki/Are-you-part-of-the-GitHub-BC-Gov-Org?.md create mode 100644 wiki/CSS-API-Account.md create mode 100644 wiki/CSS-App-My-Teams.md create mode 100644 wiki/CSS-App-Valid-Redirect-URI-Format.md create mode 100644 wiki/Creating-a-Role.md create mode 100644 wiki/Gold-Custom-Realm-Community-Ways-of-Working.md create mode 100644 wiki/Identity-Provider-Attribute-Mapping.md create mode 100644 wiki/Our-Partners-and-Useful-Information.md create mode 100644 wiki/Pathfinder-Uptime-Monitoring.md create mode 100644 wiki/Recommend-Skipping-the-Keycloak-Login-Page-and-if-you-ABSOLUTELY-need-it.md create mode 100644 wiki/Request-to-delete-a-custom-Pathfinder-SSO-Realm.md create mode 100644 wiki/SSO-Onboarding.md create mode 100644 wiki/SSO-Pathfinder-Knowledge-Base.md create mode 100644 wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms.md create mode 100644 wiki/Useful-References.md create mode 100644 wiki/Using-Your-SSO-Client.md create mode 100644 wiki/What-is-Keycloak-@-BC-Government?.md create mode 100644 wiki/_Sidebar.md create mode 100644 wiki/index.md diff --git a/README.md b/README.md index 91570cdd..a6142b3c 100644 --- a/README.md +++ b/README.md @@ -8,3 +8,13 @@ repository for keycloak images and helm chart - GitHub Packages - Tag strategies/conventions + +## Devhub Docs + +Devhub docs are generated using [mkdocs](https://www.mkdocs.org/getting-started/). To get setup, run: +- `pip install mkdocs` +- `pip install mkdocs-techdocs-core` + +_If you get a dependency issue, e.g 'No module named '\_ctypes', you may have been missing dependencies when python was installed. Install the dependencies, in this case `sudo apt-get install libffi-dev`, update python. If using asdf, you can reinstall the python version in the .tool-version file._ + +Then run `mkdocs serve` to see the site locally. \ No newline at end of file diff --git a/catalog-info.yaml b/catalog-info.yaml new file mode 100644 index 00000000..a17c75ad --- /dev/null +++ b/catalog-info.yaml @@ -0,0 +1,12 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: "css-docs" + description: "A guide to the BC Gov Common Hosted Single Sign-on" + annotations: + github.com/project-slug: bcgov/sso-keycloak + backstage.io/techdocs-ref: dir:./wiki +spec: + type: documentation + lifecycle: production + owner: "citz" \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..d3980ea6 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,5 @@ +site_name: BC Gov Common Hosted Single Sign-on +docs_dir: wiki + +plugins: +- techdocs-core \ No newline at end of file diff --git a/wiki/Additional-Help.md b/wiki/Additional-Help.md new file mode 100644 index 00000000..b82cd56a --- /dev/null +++ b/wiki/Additional-Help.md @@ -0,0 +1,15 @@ +Many development teams have gone through similar processes in exploring Pathfinder SSO integration with their applications. When you have questions or issues, it is highly likely that someone in the community has had a similar experience previously. These issues may already have a solution or are actively resolving. Here are some ways to get Pathfinder SSO help: +- FAQ's - The Pathfinder SSO team tracks some frequently asked questions and with answers are made available through the following link: [FAQ's](https://github.com/bcgov/sso-keycloak/discussions/categories/gold-q-a). +- We encourage you to join the Pathfinder SSO community on [RocketChat](https://chat.developer.gov.bc.ca/channel/sso) and post questions there. Be specific and clear when raising questions or issues and include your user case and expected results. +- If you find a problem, issue or a bug, please create a GitHub issue [here](https://github.com/bcgov/sso-keycloak/discussions/new?category=q-a) first, and let the team know by posting in RocketChat. +- The team prefers the channels described above, but if you need to send a message to the team, please email the [Product Owner](mailto:bcgov.sso@gov.bc.ca). + +Within RocketChat if you see someone asking questions or have issues for which you may have a solution, please feel free to help out and contribute in RocketChat. We very much appreciate your contributions. + + + + +

+ +

+ diff --git a/wiki/Alerts-and-Us.md b/wiki/Alerts-and-Us.md new file mode 100644 index 00000000..9ff9be23 --- /dev/null +++ b/wiki/Alerts-and-Us.md @@ -0,0 +1,242 @@ +Here's an overview of our Service Levels and Metrics on our acknowledge and response times: +# Service Levels +We often get questions about our Service Level Agreement and over the years we've come to realize the answer is not that simple. This an attempt to plain language the our Service Levels, other systems that impact our SLA as we are a subset of a larger system, our approach to keeping systems stable and reliable, and our future thinking. + +## What is our Service +Our service, the Pathfinder SSO ensures that our Keycloak server acts as an Open ID Connect [OIDC](https://openid.net/connect/) based Identity Provider, mediating with an enterprise user directory or 3rd-party SSO providers for identity information and applications via standards-based tokens and identity assertions. + +Specifically, we make use of the Red Hat SSO v 7.6.1.GA + +**Other systems we rely on** + +The Pathfinder SSO service is hosted on the Private Cloud Openshift platform in the government data centers in Kamloops and Calgary (DR). There are planned and unplanned outages that impact the infrastructure that our service is hosted in and thus impact the availability of the service. + +**Private Cloud Platform as a Service (Platform Services)** + +We are a subset of a larger ecosystem of services within BC Government. Our Keycloak server sits on the [BCGov Private Cloud Platform as a Service aka Openshift](https://cloud.gov.bc.ca/private-cloud). +Planned outages on the Openshift platform have minimal impact on our end user uptime due to the Switchover/GoldDR process (15-30 minutes at most). + +The current availability commitments for the Gold/Gold DR Openshift service is 99.95%. + +Reference: [Private Cloud Memorandum of Understanding](https://cloud.gov.bc.ca/private-cloud/our-services-in-private-cloud-paas/memorandum-of-understanding-for-private-cloud-paas/) and [Private Cloud Hosting Tiers](https://cloud.gov.bc.ca/private-cloud/our-products-in-the-private-cloud-paas/silver-and-gold-tier-platforms/) + +**BC Government Kamloops and Calgary Data Centers** + +It should be noted together with the Private Cloud/Platform Services Team we are reliant on the service levels agreed upon by the +Province an the Kamloops/Calgary Data Centers. The unplanned outage to the Data Centers are out of our control and impact our Service Level Target. + +The current availability commitments for the Data Centers are 99.5%. + + +**Identity Partners** + +We have a healthy relationship with our Access Directory Management Services (ADMS/WAM) team and the Provincial Identity Information Management (IDIM) team who are the identity providers for IDIR and BCeID. Any unplanned outages or impact to these identity services are out of our control and impact our Service Level Target. + + + +### Our Service Level Target 2023 + +Working as DevOps Agile team maintaining high system availability and reliability is paramount to our Service Levels. + +We aim to keep our Service available 99.95% noting that some months we may be 99.9% due to linked systems and their outages beyond our control. + +This is SLA is is based on the highest SLA for the services we rely on. + +**What does 99.99, 99.95 vs 99.9 mean?** + +99.99 translates to 4 min of downtime/outage mode a month + +99.95 translates to 21 min of downtime/outage mode a month + +99.9 translates to 40 min of downtime/outage mode a month + +#### Service Level Defined +As of writing (April 2023) we define our service levels as: + +• Our service is available 24/7, except during planned outages within the Kamloops and Calgary data centres. Planned outages are communicated through [RocketChat](https://chat.developer.gov.bc.ca/channel/sso) + +• Our regular business hours are weekdays from 9:00 am to 5:00 pm Pacific Time, excluding statutory holidays. Client provisioning questions and requests will be reviewed and handled during normal business hours. After hours support is provided by the Pathfinder SSO team, and is only available for service outages and other incidents that impact the service + +• To learn more about our service uptime monitoring, please [visit our uptime page on our wiki](https://github.com/bcgov/sso-keycloak/wiki/Pathfinder-Uptime-Monitoring) and join our [newsletter](https://subscribe.developer.gov.bc.ca/) to receive important updates on the service and any outages. + + +**Our approach to stability and reliability (Support Incident Response Times)** + +The Pathfinder SSO Team responds to 3 levels or incidents: P1 - Critical, P3 - Moderate and P4 - Low. + +The team responds to all service incidents through our 24/7 process where our team is alerted of the incident. Our target response times are: + +> P1 - Critical - respond within 20mins +> +> P3 - Moderate - respond within 30 mins +> +> P4 - Low - respond within 45 mins +> + +As a very responsive team, you will see our metrics over the years and that we respond very quickly [2022 and 2023 Recap of Alerts/Incidents](https://github.com/bcgov/sso-keycloak/wiki/Alerts-and-Us#metrics) + +It should be noted that our current version of Redhat SSO does not enable us to offer zero downtime aka [blue green deployments](https://docs.aws.amazon.com/whitepapers/latest/introduction-devops-aws/blue-green-deployments.html). As a result, when we need to upgrade our Redhat SSO version or need to apply a patch, we advise our clients in advance via [RocketChat](https://chat.developer.gov.bc.ca/channel/sso) with a note that active sessions may be lost ie: end users may have to login again. + + +**Change Communications** + +When a change occurs on our service, we will provide notification in advance in these ways: + +**Minor changes** are announced 24 hours in advance in the [Rocket.Chat #sso channel.](https://chat.developer.gov.bc.ca/channel/sso) An example of a minor change is tied to small bug fixes or other low-impact changes. + +**Emergency change**s are announced as soon as possible in advance in the [Rocket.Chat #sso channel.](https://chat.developer.gov.bc.ca/channel/sso) channel. An emergency change is performed to recover a failed service, prevent a failure or address a security vulnerability. + +**Medium/Major changes** are announced five (5) business days in advance in the [Rocket.Chat #sso channel.](https://chat.developer.gov.bc.ca/channel/sso) channel. An example of a medium change is an upgrade to the keycloak version number, with limited impacts. + + +##### Our Service Uptime + +We do make use of uptime monitoring to help report out on our service levels. We monitor 3 things with uptime: +1. Is our service up? +2. Can any user get in? +3. Can a user affiliated with an identity provider ie IDIR user get in? + + + +[See more details](https://uptime.com/statuspage/bcgov-sso-gold) + +**Cost** + +There is no cost for the BC Gov's Pathfinder SSO service for B.C. government ministries, central agencies, and Crown corporations in the 2023/2024 fiscal year. There may be a cost model introduced in the following fiscal years. To receive updates, sign up for the [sso newsletter](https://subscribe.developer.gov.bc.ca/). + +**Future Thinking** +As a [DevOps Agile team](https://aws.amazon.com/devops/what-is-devops/) , we want to minimize the downtime our clients have. Our current focus is to complete our Openshift Silver Keycloak migration to Openshift Gold Keycloak and then we hope to have cycles to innovate and pursue zero down time (eventually move to [ROSA](https://aws.amazon.com/rosa/) or maybe when Redhat SSO is linked with [Keycloak Quarkus](https://www.keycloak.org/downloads). +Join our monthly open demos as we share where we are going. + + + +# Metrics + +## Historic Uptime + +The uptime for a given alert over a range by using a custom range on the alert screen: +![image](https://github.com/bcgov/sso-keycloak/assets/9705602/d7c3492b-af1f-451d-bcec-f415d563a0ef) +Uptime will calculate the total downtime for the alert +![image](https://github.com/bcgov/sso-keycloak/assets/9705602/7892e68c-8534-4f56-87d9-1a42aac60003) + + +### Gold Keycloak SSO Prod End User Access Uptime +| Month | Downtime | +| -------- | ------- | +| January 2023 | 41m 6s | +| February 2023 | 36m 21s | +| March | 0 | +| April 2023 | 1h5m30s | +| May 2023 | 51m00s | +| June 2023 | 0 | +| July 2023 | 0 | +| August 2023 | 0 | +| September 2023 | 0 | +| October 2023 | 0h27m2s | + +### Gold KeyCloak SSO Prod and IDIR siteminder Uptime +| Month | Downtime | +| -------- | ------- | +| January 2023 | 1h0m18s | +| February 2023 | 38m12 | +| March | 56m40s | +| April 2023 | 1h51m46s | +| May 2023 | 1h38m45s | +| June 2023 | 0 | +| July 2023 | 6m 43s | +| August 2023 | 0 | +| September 2023 | 0 | +| October 2023 | 0h35m25s | + +## 2023 +### Incidents +#### Priority 1 aka Critical Impact to Service -- no end users can log into their apps connected to keycloak +Pathfinder Team commits to acknowledging issue within 15 -20 mins and resolving as quickly as possible +##### P1 Stats +| Month | Number of Alerts | Acknowledge Time | Resolve Time | Notes | +| :--- | :----: | :----: | ---: |---: | +| January | 6 | 2min 11s | 45m 26s | Jan 25 & Jan 24 - OCP Upgrade | +| February | 0 | 0 | 0| 0 | +| March | 16 | 1m 10s | 5m24| March 2& 3 intermittent idir issues March 6 tied to sm vendor guidance. March 18 tied to platform services work| +| April | 7 | 2m22s | 6m48s| April 4 uptime time out issue. April 5 Prod fixes by us. April 11 uptime Global script execution timeout | +| May | 21 | 6m08s | 20m57s| May 24 CPU surge that may have been caused by logging, May 28 STMS work triggered timeouts | +| June | 1 | 0m01s | 0m01s| June 12: CPU spike over 5, not outage, Gold Upgrade Day | +| July | 2 | 0m31s | 4m09s| July 28: CPU spike over 5, and Idir login failure. Caused by CPU surge in the Keycloak Pods, discussion with RedHat to resolve root cause | +| August | 1 | 0m39s | 3m28s| Aug 1: Uptime failed check, carryover from July outage| +| September| 0 | 0 | 0| NA| +| October| 3 | 2m12s | 19m55s| Oct 16 CPU spike causing lag on login (end-users still able to log in, system slow) Oct 18 short uptime misfire in alerting | + +#### Priority 3 aka Moderate Impact to Service -- +Pathfinder Team commits to acknowledging issue within 15 -30 mins and resolving as quickly as possible +##### P3 Stats +| Month | Number of Alerts | Acknowledge Time | Resolve Time | Notes | +| :--- | :----: | :----: | ---: |---: | +| January | 3 | 12 min52s | 14m 19s | Jan 25 & Jan 24 - OCP Upgrade | +| February | 8 | 6m 51s | 7m 41s | Feb 2 & Feb 13 kc upgrade; Feb 4 pvc/db size in dev; Feb 6 pods cycling? | +| March | 0 | 0 | 0 | 0 | +| April | 0 | 0 | 0 | 0 | +| May | 3 | 3m14 | 3m14 | related to silver openshift upgrade | +| June | 3 | 2m26 | 2m55 | 1 silver alert, gold upgrade on June 12 | +| July | 0 | 0m00s | 0m00s | Ops genie did trigger some call out alerts but they were unrelated to stability. | +| August | 0 | 0 | 0| NA| +| September | 1 | 21s | 21s| Not a real alert, call came in| +| October| 2 | 45m32s | 46m03s| Not real alerts, came in from the call system | + +#### Priority 4 aka Low Impact to Service -- +Pathfinder Team commits to acknowledging issue within 15 -30 mins and resolving as quickly as possible +##### P4 +| Month | Number of Alerts | Acknowledge Time | Resolve Time | Notes | +| :--- | :----: | :----: | ---: |---: | +| January | 17 | 9min 56s | 46m 15s | Jan 25 & Jan 24 - OCP Upgrade | +| February | 15 | 13m 12s | 15m 41s 0 | +| March | 5 | 12m 53s | 16m 48s | siteminder in dev and test; db pvc over 90%; Gold cpu usage med +| April | 13 | 2m53s | 7m49s | April 5 Prod fixes by us. April 11 uptime Global script execution timeout | +| May | 23 | 7m41s | 29m11s | May 24 CPU surge, May 28 STMS work, May 30 PVC warning | +| June | 5 | 2m09s | 2m36s | June 12 gold upgrade | +| July | 12 | 2m41s | 5m41s | July 5, July 11, July 25 - backup PV size warning, July 27 and 28 Had 'low pod' and 'cpu spike' warnings. Resolved by cycling the pods. Discussions with Redhat resolved the root issue. | +| August | 0 | 0 | 0| NA| +| September | 7 | 1m24s | 1m25s| Backup DB at 60% the other 6 were ready pods low, triggered during a keycloak pod roll over manually triggered| +| October| 14 | 17m03s | 17m17s| 8 dev or test uptime alerts, 6 ready pod low alerts for prod (natural part of cycling pods) | + + + +### Total mins of outages +TBD + +### 2022 +#### P1 +| Month | Number of Alerts | Acknowledge Time | Resolve Time | Notes | +| :--- | :----: | :----: | ---: |---: | +| June | 25 | 3m 43s | 4m 10s | | +| July | 2| 8m 17s | 9m 44ss | | +| August | 6 | 11m 37s | 8h 45 m | _siteminder/network issue [Aug 5](https://chat.developer.gov.bc.ca/channel/sso?msg=FpfxtgJN9BEfMaenC)_ Aug 17 tbd | +| September | 19 | 9m 22s | 30m 5s | Sept 7, [sept 12](https://chat.developer.gov.bc.ca/channel/sso?msg=YpwwatnNGnTRc7q3J), [Sept 25](https://chat.developer.gov.bc.ca/channel/sso?msg=hWAzCD7GMM7Wyy2q7) | +| October | 4 | 12m 31s | 16m 37s | oct 5, Oct 12 Oct 23 Oct 27| +| November | 0 | 0 | 0 | 0| +| December| 0 | 0 | 0 | 0| + + +#### P3 +| Month | Number of Alerts | Acknowledge Time | Response Time | +| :--- | :----: | :----: | ---: | +| June | 30 | 7m 32s | 27m 23ss | +| July | 2 |10m 55s | 10m 58s | +| August | 3 | 6m 5s | 6m 34s | +| sept | 4 |3m 15s | 1 h 18m 46s | | +| Oct | | | | +| Nov | | | | +| Dec | 2 | 9m 8s| 20m 59s | + + +#### P4 +| Month | Number of Alerts | Acknowledge Time | Response Time | +| :--- | :----: | :----: | ---: | +| June | 27 | 14m 9s | 15m 50s | +| July | 2 |10m 55s | 10m 58s | +| August | 3 | 6m 5s | 6m 34s | +| sept | 7|2m 2s | 2m 13s | | +| Oct | 4 | 1m 18s | 1m 18s | +| Nov | 5 | 22m 35s | 36m 9s | +| Dec | 14 | 2m 29s | 2m 49s | + + diff --git a/wiki/Are-you-part-of-the-GitHub-BC-Gov-Org?.md b/wiki/Are-you-part-of-the-GitHub-BC-Gov-Org?.md new file mode 100644 index 00000000..8939365f --- /dev/null +++ b/wiki/Are-you-part-of-the-GitHub-BC-Gov-Org?.md @@ -0,0 +1,14 @@ +You have been redirected to this page because your github account is not affiliated with the organization `bcgov`. +To find out if you are affiliated, go to your github profile and look at the organizations you are associated with. You will not see `bcgov`. + + + + +### [If you need to be included in this org, please read and follow the instructions here](https://docs.developer.gov.bc.ca/bc-government-organizations-in-github/#organizations-in-github). + + + + + + + diff --git a/wiki/CSS-API-Account.md b/wiki/CSS-API-Account.md new file mode 100644 index 00000000..3e232134 --- /dev/null +++ b/wiki/CSS-API-Account.md @@ -0,0 +1,38 @@ +The SSO CSS API let's you interact with CSS Application in a RESTful way for both user and role management. To get the access to this API, an admin from a team needs to request CSS API Account through CSS Application. + +## How to request a CSS API Account: + +1. Login to CSS Application and select `My Dashboard` tab +1. Navigate to `My Teams` tab and select a team. [More on teams here](https://github.com/bcgov/sso-keycloak/wiki/CSS-App-My-Teams) +1. Select `CSS API Account` tab and click on `+ Request CSS API Account` to request for an API Account +1. The request shall be approved within 20 minutes and you shall be provided with the options to `copy` or `download` your CSS API Account credentials + +## How to use CSS API: + +1. CSS API is protected by OAuth2 client credentials flow, so a token is mandatory to make requests to CSS API +1. You can acquire a bearer token using your CSS API Account credentials +1. Add this token in the `Authorization` header in the form of `Bearer ` and make a request to the API +1. The OpenAPI Spec of the CSS API can be accessed at https://api.loginproxy.gov.bc.ca/openapi/swagger +1. Note the token endpoint will be: https://loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/token + +## How to delete CSS API Account: + +1. Login to CSS Application and select `My Dashboard` tab +1. Navigate to `My Teams` tab and select a team +1. Under `CSS API Account` tab, you can find delete icon to delete your CSS API Account for that team + +## FAQs +### Q: How many CSS API Accounts are permitted per team? +A: Only one CSS API Account is permitted per team + +### Q: Can I use my CSS API Account to manage other team's integrations? +A: No, your CSS API Account is used only to manage your team's integrations + +### Q: Can I use my CSS API Account to manage all my team's integrations in silver and gold clusters? +A: No, your CSS API Account is used only to manage your team's gold integrations + +### Q: Do I need to delete CSS API Account before deleting a team? +A: When the team is deleted, the associated CSS API Account gets deleted automatically + +### Q: Do I need to create an integration before requesting CSS API Account? +A: You can request CSS API Account even if there are no integrations associated with your team \ No newline at end of file diff --git a/wiki/CSS-App-My-Teams.md b/wiki/CSS-App-My-Teams.md new file mode 100644 index 00000000..fbf3b725 --- /dev/null +++ b/wiki/CSS-App-My-Teams.md @@ -0,0 +1,95 @@ +# Overview of My Teams +We've heard from our clients on the value of our product, the Common Hosted Single Sign On (CSS) App and a request for a feature to allow others to have access to the integrations you create with our CSS App, so let's talk about the concept of Teams! + +Within the CSS App, you can create a team which allows you to add others to your team, manage the integration and manage the CSS API account you've requested. + +## How do I create a team? + +There are two ways to create teams within the CSS app. + +Method 1: Go to my “My Teams” tab, and select the “+Create a New Team” button. + +Method 2: Go to the “My Projects” tab, select “+Request SSO Integration”, and select “Yes” for creating a project team. + +#### Relationship between Teams and Projects + +A team can be associated to one or more projects/integrations. + + + +### I've created a team, now what? + +You're an **admin**: When you create a Team, you are automatically assigned an Admin role. As an Admin, your permissions let you manage both Integrations and Teams. + +You can add other _**team members**_: You can add others to your team with either the Admin role or Member role. The key difference is that Admins can manage teams and Members cannot. + + +#### Managing an integration +When creating a team, you can assign this team to one integration, or several integrations. This will allow all users on the team to view and manage the integration. Here's a table to show the difference between what a **Team Admin** and a _**Team Member**_ can do with an integration: + +| Managing Integration(s) Function | Admin Role | Team Member Role | +| ----------- | ----------- | ----------- | +| Create | **Admin** | _**Team Member**_ | +| View | **Admin** | _**Team Member**_ | +| Edit | **Admin** | _**Team Member**_ | +| Delete| **Admin** | N/A | + + + +#### Managing a team as an Admin +Users with the **Admin** role can manage teams. + +##### Adding New Team Members: + +**Admins** can add new users to a Team, and assign users as either Admins or Members. + +To add a new Team member, **Admins** must use a government email address, to ensure the user can login to the app. Once an invitation is sent, the new team member have 2 business days to login to the CSS App to be added to the team. If the team member is unable to login within this time period, their invitation link will expire. In this case, Admins can resend the invitation link from the Dashboard, under the “My Teams” tab. + +##### Changing Team Members Roles & Deleting Team Members: + +Under the “My Teams” tab, **Admins** can also change a user’s role, or delete the user + +##### Here's a table to show what an Admin and a Team member can do with a team + +Here's a table to show the difference between what a Team Admin and a Team Member can do with an integration: +*Note: Anyone with an IDIR account can create a team and become the Admin + +| Managing Team(s) Function | Admin Role | Team Member Role | +| ----------- | ----------- | ----------- | +| Create Team Name and Membership| **Admin** | N/A | +| View Team Name and Members | **Admin** | _**Team Member**_ | +| Edit Team Name | **Admin** | N/A | +| Delete Team | **Admin** | N/A | +| Assign Team Members | **Admin** | N/A | +| Unassign Team Members | **Admin** | N/A | + +#### Managing a Role associated to Integration + +When creating an integration, some teams may want to create roles associated to the integration. More on roles here https://github.com/bcgov/sso-keycloak/wiki/Creating-a-Role + +Only an **Admin** can create roles and once the roles are created, Admins and Members can assign users to the role. + +| Managing Roles Associated to Integration Function | Admin Role | Team Member Role | +| ----------- | ----------- | ----------- | +| Create Role Name| **Admin** | N/A | +| View Role Name | **Admin** | _**Team Member**_ | +| Edit Role Name | **Admin** | N/A | +| Delete Role Name | **Admin** | N/A | + +| Assigning Users to Roles Associated to Integration Function | Admin Role | Team Member Role | +| ----------- | ----------- | ----------- | +| Assign User to Role | **Admin** | _**Team Member**_ | +| View Users of a specific Role | **Admin** | _**Team Member**_ | +| Unassign User to Role | **Admin** | _**Team Member**_ | + + +#### Managing Access to CSS API Account + +**Admins** can also create a CSS API Account for a team, which will allow you to interact with CSS Application in a RESTful way for both user and role management. [Learn more about the CSS API Account in our wiki page.](https://github.com/bcgov/sso-keycloak/wiki/CSS-API-Account) + +| Managing Access to CSS API Function | Admin Role | Team Member Role | +| ----------- | ----------- | ----------- | +| Create API Account| **Admin** | N/A | +| View/Download API Account | **Admin** | N/A | +| Delete API Account | **Admin** | N/A | + diff --git a/wiki/CSS-App-Valid-Redirect-URI-Format.md b/wiki/CSS-App-Valid-Redirect-URI-Format.md new file mode 100644 index 00000000..35a3fb9b --- /dev/null +++ b/wiki/CSS-App-Valid-Redirect-URI-Format.md @@ -0,0 +1,9 @@ +In CSS app, the allowed URI syntax consists of two parts with `://` in the middle: +- `://` +- `scheme`: the following rules must be met: + 1. must be greater than one character. + 2. must start with an alphabet character followed by optional characters (`alphabets`, `hyphens(-)`, and `periods(.)`) +- `path`: a minimum of one character is required except for `white spaces` and `#`. +- For the `dev` and `test` redirect URIs please refer to the regular expression `/^[a-zA-Z][a-zA-Z-\.]*:\/\/\S+/` +- For `prod` URIs there are additional restrictions on wildcards (*) please refer to the regular expression `/^[a-zA-Z][a-zA-Z-\.]*:\/\/([^*\s]+\/\S*|[^*\s]*[^*\s]$)/`. This prevents domain level wildcards like `https://www.example.com*` while accepting non-domain level wildcards `https://www.example.com/*`. +* We made an exception to allow wildcard (*) in the dev, and test environments to satisfy the various development processes. \ No newline at end of file diff --git a/wiki/Creating-a-Role.md b/wiki/Creating-a-Role.md new file mode 100644 index 00000000..1f416069 --- /dev/null +++ b/wiki/Creating-a-Role.md @@ -0,0 +1,69 @@ + +*** + +You've asked and we've listened, we've created the ability for you to create roles for your SSO integration. + +### What are roles in the Common Hosted Single Sign On (CSS) App? + +Roles identify a type or category of user. Admin, user, manager, and employee are all typical roles that may exist in an organization. Applications often assign access and permissions to specific roles rather than individual users as dealing with users can be too fine-grained and hard to manage. + + +The CSS App provides the ability to add roles to an integration. This concept is also known as Role-based access control (RBAC), a mechanism that restricts system access. + +### Why use roles? + +You can use roles to enable access to specific pages or data to only those users who connect, with efficiency, data security and simplicity under consideration. + + + + + + + + + +### How to create a Role: +[View a quick video of how to create Roles](https://github.com/bcgov/sso-keycloak/assets/56739669/435f502a-aed8-49de-9ff7-f64dd4a38ff0), or continue reading the instructions below. + + + + + + +### How to create a Role: +1. First, create your integration +1. Once your integration status becomes “Completed”, you can “Create a New Role” for each of your environments, under Role Management +1. Next, you can add users to your various roles, under Assign Users to Roles +1. Finally, configure your app to make use of these roles that are passed via the access token/payload + +### Once you have your **JSON** Details and created a **Role** +1. Once your integration is in "completed" status, you will have your json details AND you have created at least one Role +1. Make sure you assign at least one person to this role under the "Assign Users to Role" section +1. Log in to your Application +1. Look for the Role you created in the client_roles attribute View this [video at 1:35](https://user-images.githubusercontent.com/56739669/231529538-0e1efa5a-51df-401a-99c2-dbc964e8cac6.mp4) + + +### A couple of notes: +1. A Role can **only** be created once the integration status is “completed" +1. You have the ability to create different roles for each of the different environment(s) in your integration +1. When you select a role, the right hand side will show users assigned to that role +1. By deleting a role, you are also removing the role from the users assigned to the role....it’s on our backlog to allow to delete one user at a time +1. Any Team Member within your integration can create OR delete roles * +1. Any Team Member within your integration can see all users assigned to role + +( * ) we've got it in our backlog to configure team admins to handle role management( create/delete roles) and team members to handle user assignment (add/remove users to roles) + + +## Service Account Role Management + +Some client teams require roles to be created for their service accounts. Examples include granting permissions to service accounts to access different endpoints of client API + +We've heard from clients the need to create roles on service accounts and as a community member in our SHARED/STANDARD service, please keep in mind, that other teams may use the same role names as you. For this reason and for good security posture, your API end point checks should look at the `aud`. **Audience check is required if you have an API for your application and you have a standard integration.** + + +From the wisest of our team member "One final note which is paramount; securing your API endpoints. If you're using the standard realm then you'll have to use a combination of roles (created in CSS), issuer & audience (as well as the public key) to confirm the token is indeed valid for your API. Otherwise, other teams in the same realm would have the ability to make the same call" + +*** + +*** diff --git a/wiki/Gold-Custom-Realm-Community-Ways-of-Working.md b/wiki/Gold-Custom-Realm-Community-Ways-of-Working.md new file mode 100644 index 00000000..500dccf6 --- /dev/null +++ b/wiki/Gold-Custom-Realm-Community-Ways-of-Working.md @@ -0,0 +1,2 @@ +Please visit our updated material here +https://bcgov.github.io/sso-docs/best-practices/gold-way-work \ No newline at end of file diff --git a/wiki/Identity-Provider-Attribute-Mapping.md b/wiki/Identity-Provider-Attribute-Mapping.md new file mode 100644 index 00000000..c2a37946 --- /dev/null +++ b/wiki/Identity-Provider-Attribute-Mapping.md @@ -0,0 +1,12 @@ +IDP mappers_ June2023 + +GitHub_IDP_Mappers _ June2023 + + +* Any other attribute can be fetched by the app itself using [IDIM Web Services](https://sminfo.gov.bc.ca/) + + +[Another way to view this from a developer perspective](https://bcgov.github.io/sso-docs/advanced/Custom%20Realms/identity-mappers) + +## Playground +[Try our playground to see what comes in the payload with your client integration](https://bcgov.github.io/keycloak-example-apps/) \ No newline at end of file diff --git a/wiki/Our-Partners-and-Useful-Information.md b/wiki/Our-Partners-and-Useful-Information.md new file mode 100644 index 00000000..ea716271 --- /dev/null +++ b/wiki/Our-Partners-and-Useful-Information.md @@ -0,0 +1,124 @@ + + +## Navigation +- [What are identity providers, and which are available to BC Government?](#What-are-identity-providers) +- [Azure IDIR and IDIR - What's the difference?](#Azure-IDIR-and-IDIR) +- [Common Login Errors](#common-login-errors) +- [BC Service Card Integration](#BC-service-card-integration) +- [Identity Provider Attribute Mapping](https://github.com/bcgov/sso-keycloak/wiki/Identity-Provider-Attribute-Mapping) +- [BC Government Identity Standards aka IM/IT Identity Standards](https://www2.gov.bc.ca/gov/content/governments/services-for-government/policies-procedures/im-it-standards/find-a-standard#id_mgt) + + +## What are identity providers? + +[Identity providers](https://github.com/bcgov/sso-keycloak/wiki/Useful-References#identity-provider) are directories of user accounts with details about those users, called attributes. The ones available to Pathfinder SSO Clients are: +- **IDIR** IDIR accounts are given to individuals who work for the B.C. government. Each account has an IDIR username and password for logging in. [reference](https://www2.gov.bc.ca/gov/content/governments/services-for-government/information-management-technology/identity-and-authentication-services/login-best-practices/language-consistency) + +- **Azure IDIR** IDIR accounts with the added the benefit of MFA (multi-factor authentication). This is a step up security-wise from regular IDIR. [reference](https://intranet.gov.bc.ca/thehub/ocio/ocio-enterprise-services/information-security-branch/information-security-mfa/mfa-registration) + +- **BCeID** BCeID Accounts enable people to access government services using a single identifier and password.[reference](https://www2.gov.bc.ca/gov/content/governments/services-for-government/information-management-technology/identity-and-authentication-services/bceid-authentication-service) + +- **BCSC (BC Services Card)** The BC Services Card provides access to government services for B.C. residents [reference](https://www2.gov.bc.ca/gov/content/governments/government-id/bc-services-card/log-in-with-card) + +- **Digital Credential** These are the digital equivalents of physical credentials and used with a secured digital wallet for managing and storing.[reference](https://digital.gov.bc.ca/digital-trust/about/what-are-digital-credentials/) + + +- **GitHub associated with BC Gov Org** Allows login of GitHub BC Gov Org member. At the time of writing, production approval for this requires you to obtain an exemption to the IM/IT standards. [IM/IT Standards Frequently Asked Questions](https://www2.gov.bc.ca/gov/content/governments/services-for-government/policies-procedures/im-it-standards/im-it-standards-faqs) + + +## Azure IDIR and IDIR? +Using Azure IDIR adds the benefit of MFA (multi-factor authentication). This is a step up security-wise from regular IDIR. + +You may have to educate your end users on MFA and please take note if your IDIR is not tied to a gov.bc.ca email address, please use idir_username@gov.bc.ca when prompted for your email. + +You can **learn** [here from our IDIR Partner](https://intranet.gov.bc.ca/thehub/ocio/ocio-enterprise-services/information-security-branch/information-security-mfa/mfa-registration) + +Also note if you get an error message similar to the one below, please ensure the end user has an BC Gov Azure IDIR account in order to gain access. + + +## Common Login Errors + +### IDIR and BCeID in the same browser + +As we partner with the BC Gov Identity Partners of IDIR and BCeID please note in the same browser, you cannot have one tab logged in with IDIR and another with BCeID. + +Please use a private browser by either using incognito or clearing your cache. + +### Other issues + +Please ensure you have tested with an incognito browser as mentioned above. If it is still an issue, reachout to use on [rocketchat](https://chat.developer.gov.bc.ca/channel/sso) + +## Digital Credential Configuration + +This defines which credential (or combinations of credentials) will be requested at user authentication. + +Please work with the DITP team ditp.support@gov.bc.ca to define whether an existing configuration can be used, or a new one should be created for the specific use-case. Additionally, some best practices that need to be implemented at the application level can be found [here](https://github.com/bcgov/vc-authn-oidc/blob/main/docs/BestPractices.md) + +## BC Service Card Integration +
+ +*BC Services Card provides an Open ID Connect authentication server. Integration to this service is not available in the *standard* realms.* + +The IDIM team that manages BCSC integration is responsible for safeguarding the personal information that is available in a login context. They have a business requirement that integrations to BCSC cannot be shared without IDIM approval. The standard realm is a shared environment -- if we enabled a BCSC integration in a standard realm it would be technically available to all the clients that are configured to use that realm, thus breaking the security model. + +--------------------------------- + +### Options for Teams with BCSC Requirements + +
+Join an Existing Dedicated Custom Realm +
+ +With approval from IDIM, it is possible to join an existing realm that shares the same security context as your application and already has BCSC set up. This generally means that the existing clients are all from the same ministry or sector and have the same requirements for personal information through the login process. + +There are very few instances of this pattern at this time, but it is an option that is possible with the help and approval of IDIM. + +Be that as it may, if there is a closely related project in your ministry or sector that you think would be a candidate for sharing a BCSC integration, you may wish to start the conversation with IDIM and see if it makes sense for your situation. +
+ +
+Integrate Directly with BCSC +
+ +Since IDIM provides an OIDC service for BCSC, your app can integrate directly with that service instead of brokering through Pathfinder SSO. Their security practices usually require a client per application in any case, so your architecture might not require using Pathfinder SSO as a proxy authentication service anyway. In addition, this pattern removes one possible point of failure from the application architecture. + +Be mindful however that the SSO (Keycloak) product does offer token and session management; integrating directly with BCSC would require another form of token/session management to be used in your application. + +
+ +
+Configure and Manage Your Own Dedicated KeyCloak Server + +
+ + +KeyCloak runs on JBoss quite happily in a Docker container with a PostgreSQL backend. If you really need features provided by KeyCloak and you want to integrate with BCSC, it's possible to run your own KeyCloak server and configure your connection to BCSC by setting up your own OIDC IDP. +
+ +
+Obtain a Dedicated KeyCloak Realm on the Pathfinder SSO service + +
+ +If the service gets to the point where there are "slots" to create new dedicated realms, a BCSC identity provider can be securely configured within a realm dedicated to your team. For now, we are unable to offer new realms while we work to reduce the number down to a manageable size. +
+ +
+Other? + +
+ +Things are always evolving and the BC Government Open Source community is constantly innovating and solving problems together. Don't be afraid to jump into the #SSO RocketChat channel and see what the community recommends if you have an unusual use case or an innovative idea. Thank you for your collaboration! + + +
+ + +

+ +

+ +---------------------------- +#### *Have any questions? We would love to hear from you.* [![Semantic description of image](https://user-images.githubusercontent.com/87393930/133688357-09f82374-ba18-4402-8089-c0a989dde882.png)][2] +[2]: https://chat.developer.gov.bc.ca/channel/sso +[3]: https://[mail](mailto:bcgov.sso@gov.bc.ca)[email](mailto:bcgov.sso@gov.bc.ca) diff --git a/wiki/Pathfinder-Uptime-Monitoring.md b/wiki/Pathfinder-Uptime-Monitoring.md new file mode 100644 index 00000000..02a2e538 --- /dev/null +++ b/wiki/Pathfinder-Uptime-Monitoring.md @@ -0,0 +1,44 @@ + +# Gold Service Uptime +* [Keycloak End User uptime aka can a keycloak user log in to the Gold Service? ](https://uptime.com/s/bcgov-sso-gold/1391032) +* [Keycloak Service Uptime aka is the Gold Keycloak service up?](https://uptime.com/s/bcgov-sso-gold/1389409) +* [Keycloak SSO Prod & IDIR Service Uptime aka can an IDIR user log into the Gold Service?](https://uptime.com/s/bcgov-sso-gold/1391029) +## DNS Checks +If one these DNS checks fails while the other uptime checks pass for an environment, then the app may be running in Disaster Recovery mode. +* [Dev DNS Check aka DNS Dev Passes if dev.loginproxy.gov.bc.ca points to the Gold Cluster ](https://uptime.com/statuspage/bcgov-sso-gold/1719406) +* [Test DNS Check aka DNS Test Passes if test.loginproxy.gov.bc.ca points to the Gold Cluster ](https://uptime.com/statuspage/bcgov-sso-gold/1719409) +* [Prod DNS Check aka DNS Prod Passes if loginproxy.gov.bc.ca points to the Gold Cluster ](https://uptime.com/statuspage/bcgov-sso-gold/1581586) + +[Full Listing of Uptime Monitoring](https://uptime.com/s/bcgov-sso-gold) + +[Our Service Level](https://github.com/bcgov/sso-keycloak/wiki/Alerts-and-Us#service-levels) + + +# Situations when we go into Business Continuity Mode + +## Openshift Upgrade. + +We know in advance the week Gold work will happen. Will notify community members in Rocketchat on what to expect. If during this upgrade, there is a need to cut over to our Fail Over site, we will send an email communication blast + +## Incident on Gold + +Going from our primary to fail over is something we are prepared for. You can expect us to send an email commuincation blast as well as updates in the appropriate rocketchat channels on our progress. + + +## Example Messaging + +1. The Gold Keycloak _environment_ instance is in the process of failing over to the DR cluster + +* The CSS APP is being put in Maintenance mode. Please check our [Uptime](https://uptime.com/statuspage/bcgov-sso-gold) before using our service. + +2. The Gold Keycloak _environment_ instance has failed over to the DR cluster + +* DR deployment is complete, end users continue to login to your apps using the Pathfinder SSO Service (standard or custom). +* Any changes made to a project's config using the Pathfinder SSO Service (standard or custom realm) while the app is in its failover state will be lost when the app is restored to the Primary cluster. (aka your config changes will be lost). +* The priority of this service is to maximize availability to the end users and automation. + +3. The Gold Keycloak _environment_ instance has been restored to the Primary cluster (aka back to normal). + +* We are be back to normal operations of the Pathfinder SSO Service (standard and custom). +* Changes made to a project's config using the Pathfinder SSO Service (standard or custom realm) during Disaster Recovery will be missing. +* The priority of this service is to maximize availability to the end users and automation. \ No newline at end of file diff --git a/wiki/Recommend-Skipping-the-Keycloak-Login-Page-and-if-you-ABSOLUTELY-need-it.md b/wiki/Recommend-Skipping-the-Keycloak-Login-Page-and-if-you-ABSOLUTELY-need-it.md new file mode 100644 index 00000000..e858b276 --- /dev/null +++ b/wiki/Recommend-Skipping-the-Keycloak-Login-Page-and-if-you-ABSOLUTELY-need-it.md @@ -0,0 +1,22 @@ +# We recommend to skip the Login Page but if you have a need for it, read on + +As you've read in our guidance in setting up a keycloak client do's and don'ts [here](https://github.com/bcgov/sso-keycloak/wiki/Using-Your-SSO-Client#dos-and-donts), our recommendation is to skip the [keycloak login page](https://github.com/bcgov/sso-keycloak/wiki/Using-Your-SSO-Client#do-skip-the-keycloak-login-page) ie + +**Do Skip the KeyCloak Login Page** +> In KeyCloak, if the realm that contains your client has more than one IDP configured, KeyCloak shows a page that prompts the user to select which IDP they want to log in with. Almost all teams have chosen to hide this page from their users by specifying the IDP as a query string parameter in the KeyCloak Authorization URI value behind their login button. The query string is 'kc_idp_hint'. (The IDPs available will depend on the standard realm in which your client exists.) By specifying the IDP in this way, the user will be redirected directly to the login page for the identity provider and will not see the KeyCloak login choice page at all. + +**Need dedicated text for login page** + +If you are a client of ours and have an **absolute** need to have a dedicated set of text for your login page, through [our app](https://bcgov.github.io/sso-requests), you can specify the text under the field setting **Keycloak Login Page Name** + + +![image](https://user-images.githubusercontent.com/56739669/171695377-60fa5c47-e867-4097-b140-6df8d5155cdd.png) + +#### *Have any questions? We would love to hear from you.* [![Semantic description of image](https://user-images.githubusercontent.com/87393930/133688357-09f82374-ba18-4402-8089-c0a989dde882.png)][2] + + + +[2]: https://chat.developer.gov.bc.ca/channel/sso +[3]: https://[mail](mailto:bcgov.sso@gov.bc.ca)[email](mailto:bcgov.sso@gov.bc.ca) + + diff --git a/wiki/Request-to-delete-a-custom-Pathfinder-SSO-Realm.md b/wiki/Request-to-delete-a-custom-Pathfinder-SSO-Realm.md new file mode 100644 index 00000000..01286ffb --- /dev/null +++ b/wiki/Request-to-delete-a-custom-Pathfinder-SSO-Realm.md @@ -0,0 +1,24 @@ + +As of July 2023 this is archived information that will be ressurected once our gold custom realm registry is created. + +# Step 0 +Are you the product owner or project admin/team lead? + +If not, you will need to ask one of those two people to make this request for you. +We can't process realm requests except from individuals in these roles. + +Does the Admin User have an IDIR account? + +We use IDIR authentication for Realm Admin Users, so make sure there's a valid IDIR for the assigned realm admin. + +# Step 1 +Find us on [rocketchat](https://chat.developer.gov.bc.ca/channel/sso) and include the following information + +Project Name: + +Keycloak realm: + +Admin user's Business Email Address: + + +Please note that we will only start processing your request when the you've reached out us. \ No newline at end of file diff --git a/wiki/SSO-Onboarding.md b/wiki/SSO-Onboarding.md new file mode 100644 index 00000000..ed2ef737 --- /dev/null +++ b/wiki/SSO-Onboarding.md @@ -0,0 +1,32 @@ +* [MAKING A REQUEST](#making-a-request) +* [START USING OIDC CLIENT CONFIGURATION](#start-using-your-OIDC-client-configuration) + + +![Group 1491](https://user-images.githubusercontent.com/87393930/134225781-e899275c-781e-4979-8884-03ebb4fc7f51.png) + +---------------------------------- + +## Making a Request +Use the [Common hosted Single Sign on +(CSS) App](https://bcgov.github.io/sso-requests/). If you are looking for integration for IDIR login the process is completely self-serve and takes only minutes. You will need an IDIR to log in and you _should_ be a product owner, product admin, or team lead for a project. Once the automated provisioning is complete, your client details will be available securely through the web app (*) + +(*) Note for BCeID Requests +The Pathfinder SSO team will provision your DEV and TEST clients right away. You will be provided the client name and secret for each environment via a secure channel. The PROD client will be provisioned upon approval from the IDIM team. + +(*) Note for Azure IDIR Requests +Please note the provisioning process is the same as IDIR. + +### Need to host your application on the BC Gov Cloud service? + +Please visit [BCGov Cloud Services](https://digital.gov.bc.ca/cloud/services/) + +## Start Using your OIDC Client Configuration + +Once you have your client details, you can configure your application to use the service for your application login. For helpful advice on integration see [Using Your SSO Client](https://github.com/bcgov/sso-keycloak/wiki/Using-Your-SSO-Client) or **if you are eager**, check out our [keycloak example apps](https://github.com/bcgov/keycloak-example-apps) + +#### *Have any questions? We would love to hear from you.* [![Semantic description of image](https://user-images.githubusercontent.com/87393930/133688357-09f82374-ba18-4402-8089-c0a989dde882.png)][2] +[2]: https://chat.developer.gov.bc.ca/channel/sso +[3]: https://[mail](mailto:bcgov.sso@gov.bc.ca)[email](mailto:bcgov.sso@gov.bc.ca) + + + diff --git a/wiki/SSO-Pathfinder-Knowledge-Base.md b/wiki/SSO-Pathfinder-Knowledge-Base.md new file mode 100644 index 00000000..f7f6f9b7 --- /dev/null +++ b/wiki/SSO-Pathfinder-Knowledge-Base.md @@ -0,0 +1 @@ +> ### We are working to improve this flow and in the interim please visit our [wiki](https://github.com/bcgov/sso-keycloak/wiki) \ No newline at end of file diff --git a/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms.md b/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms.md new file mode 100644 index 00000000..c5c9983f --- /dev/null +++ b/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms.md @@ -0,0 +1,3 @@ +The following diagram helps understand why we've moved from a custom service to hybrid of custom and standard service + +![](https://github.com/bcgov/sso-realm-registry/blob/dev/app/public/home-right.png) \ No newline at end of file diff --git a/wiki/Useful-References.md b/wiki/Useful-References.md new file mode 100644 index 00000000..9bab8c84 --- /dev/null +++ b/wiki/Useful-References.md @@ -0,0 +1,80 @@ +* [Intro to terms](#Intro-to-terms) +* [How we describe Keycloak](#keycloak-how-we-describe-it) +* [Newbie Guide: Concepts and Terms](#newbie-guide) +* [Learn about the Open ID connect and OAuth Protocols](#Learn-about-the-Open-ID-connect-and-OAuth-Protocols) +* [Our Youtube videos on OIDC 101](#oidc-101) +* [Learn about Keycloak and its APIs](#Learn-about-Keycloak-and-its-APIs) +* [How to set up and use your KeyCloak Client](#How-to-set-up-and-use-your-KeyCloak-Client) +* [Q&A with Us](#qa-with-us) + + + +## Intro to terms + +### Authentication + +Authentication is the process of verifying who someone is + +### Authorization + +Authorization is the process of verifying what specific applications, files, and data a user has access to. For further detail on the OAuth2 flow being used for clients in the standard realm, please see the [Authorization Code Flow](https://auth0.com/docs/authorization/flows/authorization-code-flow). + + +### Identity Provider + +An "Identity Provider" is the holder of the identity that is used to log in with. The Pathfinder SSO service is NOT an identity provider. When a user of your application logs in, they will not be providing credentials to your application directly, or even to the Pathfinder SSO service. They will be logging in directly with the identity provider. That login event is then propagated back to your application in the form of a token that proves that they have logged in correctly. + +[Visit this FAQ](https://github.com/bcgov/sso-keycloak/discussions/256) on which Identity Provider might be best for you + +### [Keycloak how we describe it](https://github.com/bcgov/sso-keycloak/wiki/What-is-Keycloak-@-BC-Government%3F#what-is-keycloak) + +### Newbie Guide + +Visit [this page](https://github.com/bcgov/sso-keycloak/discussions/136) to understand key concepts and terms as you make use of our Self Service application to integrate your digital application with a with BC government approved login option. + + +## Learn about the Open ID connect and OAuth Protocols +### Readings for OAuth 2.0: +- https://tools.ietf.org/html/rfc6749 +- https://brockallen.com/2019/01/03/the-state-of-the-implicit-flow-in-oauth2/ +- https://tools.ietf.org/html/rfc6819 +- https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13 +- https://tools.ietf.org/html/draft-parecki-oauth-browser-based-apps-02 + +### OIDC 101 + [Example Repository](https://github.com/bcgov/keycloak-example-apps ) + + [Our videos material from August 2023 Iteration on OIDC Learning ](https://www.youtube.com/playlist?list=PL9CV_8JBQHirMRjBk62jeYUE_MpE4unU8) + + [Nithin's ppt](TBD) + + [Powerpoint of OIDC and OAuth](https://github.com/bcgov/sso-keycloak/files/12422946/oidc-oauth-presentationk-beta.pptx) + +The following links are a good introduction or refresher to the OIDC standard. +- [SAML2 vs JWT: Understanding OpenID Connect Part 1](https://medium.com/@robert.broeckelmann/saml2-vs-jwt-understanding-openid-connect-part-1-fffe0d50f953) +- [SAML2 vs JWT: Understanding OpenID Connect Part 2](https://medium.com/@robert.broeckelmann/saml2-vs-jwt-understanding-openid-connect-part-2-f361ca867baa) + + + +## Learn about Keycloak and its APIs + +* [Red Hat SSO (Keycloak)](https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.4/) +* [Realm Admin guide](https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.4/html/server_administration_guide/index) +* [API usage](https://access.redhat.com/webassets/avalon/d/red-hat-single-sign-on/version-7.4/restapi/) +## How to set up and use your KeyCloak Client +- [How OIDC authorization code flow works with a public client](https://www.pingidentity.com/en/company/blog/posts/2018/securely-using-oidc-authorization-code-flow-public-client-single-page-apps.html) + +## Q&A with Us + +[Github Discussions Q&A on Gold](https://github.com/bcgov/sso-keycloak/discussions/categories/gold-q-a) + +[Stackover flow Collection 1 on Keycloak/RedHat SSO](https://stackoverflow.developer.gov.bc.ca/collections/179) + +[Stackover flow Collection 2 on Custom Realms](https://stackoverflow.developer.gov.bc.ca/search?q=custom+realm) + + + +#### *Have any questions? We would love to hear from you.* [![Semantic description of image](https://user-images.githubusercontent.com/87393930/133688357-09f82374-ba18-4402-8089-c0a989dde882.png)][2] +[2]: https://chat.developer.gov.bc.ca/channel/sso +[3]: https://[mail](mailto:bcgov.sso@gov.bc.ca)[email](mailto:bcgov.sso@gov.bc.ca) + diff --git a/wiki/Using-Your-SSO-Client.md b/wiki/Using-Your-SSO-Client.md new file mode 100644 index 00000000..96110dc8 --- /dev/null +++ b/wiki/Using-Your-SSO-Client.md @@ -0,0 +1,333 @@ +
+We are in a transition, please visit us here https://bcgov.github.io/sso-docs/category/integrating-your-application + +The section below will be deleted before December 31 2023 + +## Table of Contents +- [Introduction to key concepts and terms (newbie guide)](#Introduction-to-key-concepts-and-terms) +- [Openshift Clusters](#openshift-clusters) + - [RedHat SSO Version](#redhat-sso-version) +- [Environments and Accounts](#Environments-and-accounts) + - [IDIR & GitHub Accounts](https://github.com/bcgov/sso-keycloak/wiki/Using-Your-SSO-Client#idir--github-accounts) + - [BCeID Accounts](#bceid-accounts) +- [Technical Details](#technical-details) + - [OIDC Setup and Keycloak's Authentication Flow](#oidc-setup-and-keycloaks-authentication-flow) + - [Confidential vs Private Client](#confidential-vs-private-client) + - [Using PKCE](#using-pkce) + - [Select a Usecase](#usecases) +- [Setting Up your Redirect URIs](#setting-up-your-redirect-uris) + - [Specifying redirect uris are important](#specifying-redirect-uris-are-important) + - [Valid Redirect URIs](#valid-redirect-uris) + - [Public Clients and Web Origins](#public-clients-and-web-origins) +- [Setting Up your Keycloak Client](#setting-up-your-keycloak-client) + - [Installation JSON](#installation-json) + - [Connecting to Keycloak using an adapter](#connecting-to-keycloak-using-an-adapter) + - [Connecting without an adapter](#connecting-without-an-adapter) + - [Specifying an IDP to bypass the Keycloak login page](#specifying-an-idp-to-bypass-the-keycloak-login-page) + - [A few notes on security](#a-few-notes-on-security) + - [A note on redirect URIs](#a-note-on-redirect-uris) + - [Advanced/Additional Settings](#advanced-settings) +- [CSS Account API](#css-api) +- [Dos and Don'ts](#dos-and-donts) + - [Do Not Call the KeyCloak API on Every Request](#do-not-call-the-keycloak-api-on-every-request) + - [Do Not Load Test in Production](#do-not-load-test-in-production) + - [Do Protect the Client Secret (Confidential Client Only)](#do-protect-the-client-secret-confidential-client-only) + - [Do Carefully Manage Your List of Valid Redirect URIs](#do-carefully-manage-your-list-of-valid-redirect-uris) + - [Do Skip the KeyCloak Login Page](#do-skip-the-keycloak-login-page) + - [Do Validate the IDP in the JWT](#do-validate-the-idp-in-the-jwt) + +--- +### Introduction to key concepts and terms + +Visit our [discussions page](https://github.com/bcgov/sso-keycloak/discussions/136) to understand key concepts and terms as you make use of our Self Service application to integrate your digital application with a with BC government approved login option. + +### Openshift Clusters +In mid 2022, we moved our keycloak instance from the Platform Services **Silver Openshift cluster** to their **Gold Openshift cluster**. As of June 15, 2023, all of our services will live in Gold. + +As part of the [Private Cloud Platform Openshift community](https://cloud.gov.bc.ca/private-cloud/) our service sits in the Gold Cluster which enables us to ensure our service is up 24/7. [Check out our up-to-date system health](https://uptime.com/s/bcgov-sso-gold) + +#### Redhat SSO Version + +Gold Current Version: 7.6.1.GA + +decommissioned - Silver Current Version: 7.4.9.GA + + +For Red Hat SSO & Keycloak version information, please see this link: https://access.redhat.com/articles/2342881 + + +### Environments and Accounts + +You will have a Pathfinder SSO client in each of the DEV, TEST and PROD servers. Assuming you have a DEV, TEST, and PROD environments for your application, this should give you the decoupling you need to set up each environment up with its own login context. + +##### IDIR & GitHub Accounts + +For IDIR and GitHub, your users will use "real" credentials in all three environments. + +##### BCeID Accounts + + +**With our GOLD Service** - please ensure you have BCeID accounts mapped to the correct BCeID environment listed below. For questions on test accounts, please reach out to our IDIM partners at idim.consulting@gov.bc.ca or visit [BC Gov Stack Overflow](https://stackoverflow.developer.gov.bc.ca/questions/704) + +| SSO CSS APP GOLD | BCeID Env | Visual Clue | +| ------------- |:-------------:| :-----: | +| DEV | BCeID DEV| ![image](https://user-images.githubusercontent.com/56739669/182436774-ec4f6853-9bb7-4ad7-bc2d-3422e3b8e1f3.png) | +| TEST | BCeID TEST | ![image](https://user-images.githubusercontent.com/56739669/182436317-68624f41-3889-4127-9440-20d7ec09da48.png) | +| PROD | BCeID PROD | ![image](https://user-images.githubusercontent.com/56739669/182436489-5e66b419-d3ad-4f33-b38b-92b6db6dd467.png) | + + + +** Note : If you want to point other instances of your application to your clients (such as ephemeral instances that are spun up for pull request validation or something), feel free to use DEV and TEST (but you will have to have valid redirect URIs configured for those instances). + +### Technical Details + +##### OIDC Setup and Keycloak's Authentication Flow + +All clients of Pathfinder SSO will use _Authorization Code Flow_. This is the modern, recommended OIDC setup for web applications and mobile applications. + +##### Confidential vs Public Client + +When requesting a new client you can specify whether you want it set up as a _Confidential_ client or you want it set up as a _Public Client with PKCE_. + +With a confidential client, the back-end component securely stores an application secret that allows it to communicate with the KeyCloak server to facilitate the OIDC authentication process. + +A public client is slightly less secure because there is no secret, but this configuration is required by some architectures and is supported as well. Public clients can use PKCE (Proof Key for Code Exchange) as a more secure flow. + +PKCE provides dynamic client secrets, meaning your app’s client secrets can stay secret (even without a back end for your app). PKCE is better and more secure than the implicit flow (AKA the “token flow”). If you’re using the implicit flow, then you should switch to PKCE. If you use an implicit flow to authorize your Dropbox app, then PKCE is a better, more secure replacement, and you should no longer use implicit flow. + +See the diagram below for use cases where each option is appropriate. + +![public-confidential](https://user-images.githubusercontent.com/37274633/142315233-b376b29c-4763-466c-8578-536d8f3a2ee2.png) + +#### Using PKCE + +The javascript adapter for keycloak has built-in support for using PKCE. See the documentation under the init method [here](https://www.keycloak.org/docs/latest/securing_apps/#methods), specifically the `pkceMethod`. For example, when initializing the adapter you can call `keycloak.init({ pkceMethod: 'S256' })` to use PKCE. Use the 'S256' method for you public client. + +If not using the adapter, you can use a custom implementation. This will require 4 steps: + +1. Create a `code_verifier` (cryptographically secure string) +2. Hash the code verifier with the SHA256 method to create a `code_challenge` +3. Send the code challenge and code challenge method (S256) as query parameters when redirecting users to the authorization endpoint +4. When exchanging the received code for an access token, send the initial `code_verifier` to ensure your application initiated the current exchange. + +For an example of a custom PKCE implementation, see [here](https://github.com/bcgov/sso-requests/blob/dev/app/utils/openid.ts#L20) for generating the authentication URL and [here](https://github.com/bcgov/sso-requests/blob/dev/app/utils/openid.ts#L49) for exchanging the received code for an access token. + +#### Usecases + +**Browser Login** - A web based application requiring a login component + +**Service Account** - A service account is a digital identity used by an application software or service to interact with other applications or the operating system. They are often used for machine to machine communication (M2M), for example for application programming interfaces (API). + +**Browser Login and Service Account** - A combination of the above + + +### Setting Up your Redirect URIs + +#### Specifying redirect URIs are important + +It is important to register redirect URIs as specifically as possible to prevents _bad guys_ from accessing your client and obtaining your users' information. + +- Please see [here](https://www.keycloak.org/docs/latest/server_admin/index.html#unspecific-redirect-uris_server_administration_guide) for more detail. + +#### Valid Redirect URIs + +Redirect URI(s) is a required field to enable `standard OpenID Connect redirect based authentication` with authorization code. In terms of OpenID Connect or OAuth2 specifications, this enables support of 'Authorization Code Flow' for this client. + +- Wildcards (\*) are commonly used to allow `dynamical redirect URIs` and can be added at the end of a URI only, i.e. http://host.com/* +- For local dev environment, `localhost` URIs can be used, i.e. http://localhost:3000/* + +To learn more about our format, [visit our redirect URI format page](https://github.com/bcgov/sso-keycloak/wiki/CSS-App-Valid-Redirect-URI-Format) + +#### Public Clients and Web Origins +The redirect URIs will be copied over to Keycloak Web Origins setup. In addition, adding ‘+’ to permit all origins of Valid Redirect URIs + + +### Setting Up your Keycloak Client + +##### Installation JSON + +Once your request has been completed, you will be able to download your installation file for each environment. It includes the client information to set up your SSO configuration. + +- an example Installation JSON for `confidential` client types + +```json +{ + "realm": "", + "auth-server-url": "https://.loginproxy.gov.bc.ca/auth/", + "ssl-required": "external", + "resource": "", + "credentials": { + "secret": "" + }, + "confidential-port": 0 +} +``` + +- an example Installation JSON for `public` client types + +```json +{ + "realm": "", + "auth-server-url": "https://.loginproxy.gov.bc.ca/auth/", + "ssl-required": "external", + "resource": "", + "public-client": true, + "verify-token-audience": true, + "use-resource-role-mappings": true, + "confidential-port": 0 +} +``` + +- The main difference between `confidential` and `public` clients is that `confidential` clients require `client secret`. + +#### Connecting to Keycloak using an adapter + +After having your `Installation JSON`, you can setup your application quickly using the Keycloak adapters. Keycloak has adapters for a number of languages, including java, javascript and C#. For a list of adapters and instructions on how to connect see [here](https://www.keycloak.org/docs/latest/securing_apps/index.html#openid-connect). + +- There are example applications available to demonstrate integrating with Keycloak [here](https://github.com/bcgov/keycloak-example-apps) +- In most cases, it does not require any additional information than the `Installation JSON` you can download. + +#### Connecting without an adapter + +If you are not using an adapter, you will require some additional information to set up your OpenID connection. Required information +can be found behind the publicly accessible `provider configuration endpoint` for your environment. + +Based on our integration with us, you will either have your integration connected to our Gold Standard offering. Reach out to us if you have questions. + + +##### Gold Service + +These are: + +- **Dev**: https://dev.loginproxy.gov.bc.ca/auth/realms/standard/.well-known/openid-configuration +- **Test**: https://test.loginproxy.gov.bc.ca/auth/realms/standard/.well-known/openid-configuration +- **Prod**: https://loginproxy.gov.bc.ca/auth/realms/standard/.well-known/openid-configuration + +##### OpenID Provider Metadata sample +It gives you `OpenID Provider Metadata` required for the OpenID connect configration: + +```json +{ + "issuer": "https://.loginproxy.gov.bc.ca/auth/realms/", // Issuer URL + "authorization_endpoint": "https://.loginproxy.gov.bc.ca/auth/realms//protocol/openid-connect/auth", // Authorization URL + "token_endpoint": "https://.loginproxy.gov.bc.ca/auth/realms//protocol/openid-connect/token", // Token URL + "userinfo_endpoint": "https://.loginproxy.gov.bc.ca/auth/realms//protocol/openid-connect/userinfo", // User Info UR + "end_session_endpoint": "https://.loginproxy.gov.bc.ca/auth/realms//protocol/openid-connect/logout", // Logout URL + "jwks_uri": "https://.loginproxy.gov.bc.ca/auth/realms//protocol/openid-connect/certs", // JSON Web Key Set URL + ... +} +``` + +- According to [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#OpenID.Core) documentation, _"OpenID Providers have metadata describing their configuration. These OpenID Provider Metadata values are used by OpenID Connect"_ + +- You can find the `client_id` and `client_secret` from the `Installation JSON` downloaded through the request process. +- Please see + [here](https://www.keycloak.org/docs/latest/securing_apps/index.html#endpoints) for a full list of endpoints and their descriptions. +- Please see [here](https://www.keycloak.org/docs/latest/securing_apps/index.html#other-openid-connect-libraries) for a other OpenID Connect Libraries. + +#### Specifying an IDP to bypass the Keycloak login page + +If there is more than one IDP in the realm, the Keycloak server directs your users into a login page to let them choose the IDP that they want to authenticate with. It is possible to skip the login page or override the default IDP in Keycloak by passing the optional query param" kc_idp_hint". [List of kc_idp_hints here](https://github.com/bcgov/sso-keycloak/wiki/Using-Your-SSO-Client#do-skip-the-keycloak-login-page) + +- If using an adapter, there is an option for providing `idpHint`, and +- if not, please specify it in the `Authorization URL` in your code or configuration, i.e. `http://localhost:8080/auth?kc_idp_hint=` +- Please see [here](https://www.keycloak.org/docs/latest/server_admin/index.html#_client_suggested_idp) for more detail. + +If the framework you are using prevents you from being able to pass through the _IDP hint_, please reach out to our team through rocket chat or email to ask about alternative options. + +#### A few notes on security + +The KeyCloak adapter for a Confidential client is configured in your **server-side component** because it requires a client ID and client secret that must be kept securely on the server and never provided to the user's browser. You can specify in your application logic which routes are secure and which are not. Use the adapter for this unless you really want to code your own OIDC logic. Your secure routes should invoke the adapter on each request to make sure the user is authenticated. + +If you have an insecure "Home" page, the URI to load that page should not be secured and should not invoke authentication. If you create a "Login" button that makes an http request to a secure resource, that should kick off an authentication process. Any non-public API calls to your server-side component should be secured with the KeyCloak adapter. + +#### A note on redirect URIs + +You can use any valid URI for your redirect URIs. At least one redirect URI is required for each or DEV, TEST and PROD. If you don't know the redirect URI for one or more of these environments, you may provide any valid URI for now and change it later. We suggest something like 'http://localhost:1000' + +#### Advanced settings + +Through the Common Hosted Single Sign On Application, with a suitable justification, you can request to configure the following settings + +* **Access Token Lifespan** - This setting is for the max time before an access token is expired. The value is recommended to be short relative to the SSO timeout. _Default set to 5 mins_ + +* **Client Session Idle** - this setting is the time a client session is allowed to be idle before it expires. Tokens are invalidated when a client session is expired. If not set it uses the standard SSO session idle value. _Default set to 30 mins_ + +* **Client Session Max** - this setting is the max time for a client session before it expires. Tokens are invalidated when a client session is expired. If not set it uses the standard SSO session max value. _Default set to 10hrs_ + +* **Client Offline Session Idle** - this setting is the time that client offline session is allowed to be idle before it expires. Offline tokens are invalidated when a client offline session is expired. If not set it uses the offline session idle value. _Default setting - talk to us_ + +* **Client Offline Session Max** - this setting is the max time before a client offline session is expired. Offline tokens are invalidate when a client offline session is expired. If not set, it uses the offline session max value. _Default setting - talk to us_ + +More information can be found [here](https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.5/html/server_administration_guide/managing_user_sessions#timeouts) + + + +### CSS API + +Through our engagements with our clients, we listened to your request to have an api so your apps can connect to our CSS App. Please go to [CSS API Account](https://github.com/bcgov/sso-keycloak/wiki/CSS-API-Account) of our wiki to learn more. + +Note: Often times, you do not want to be the only person with access to your client details or you may want to create multiple clients. If this the case, please visit [CSS App and My Teams](https://github.com/bcgov/sso-keycloak/wiki/CSS-App-My-Teams) for more info on Team Admins and Team Members + +### Dos and Don'ts + +#### Do Not Call the KeyCloak API on Every Request + +This can potentially bring down the shared service for all clients. This was the issue we saw with [Flask-OIDC](https://flask-oidc.readthedocs.io/en/latest/) with some teams. The adapter was making a call to the [Token Introspection Endpoint](https://www.oauth.com/oauth2-servers/token-introspection-endpoint/) with every request and it was a high-volume service. Most adapters don't do this as the token information is available within the token itself, but this one adapter seems to have a defect. + +Another important technique to be aware of is that you should cache the JWT in a cookie so that you don't have to check the status of your session with every request. Keycloak has a feature that provides a cookie for you, and libraries like keycloak-js make use of this to limit the number of round trips to the Keycloak server. + +#### Do Not Load Test in Production + +Please let the SSO team in advance when you want to do load testing in DEV and TEST so we can plan ahead and coordinate with other teams. These are shared environments that many teams are actively using. A failed load test can affect many other teams. + +#### Do Protect the Client Secret (Confidential Client Only) + +It stays on the server. Use OCP _secrets_ if you are on OpenShift. Don't put it in your public JavaScript or in your GitHub repository. Don't build it into your Docker image. + +#### Do Carefully Manage Your List of Valid Redirect URIs + +Your redirect URIs should only be resources that you control. Most of the time you will only need one URI (the one that you want the client to return to after a login event). + +#### Do Apply Appropriate Logout Calls + There is known issue with identity providers which retain session. [More info here](https://stackoverflow.developer.gov.bc.ca/questions/83) + +#### Do Skip the KeyCloak Login Page + +In KeyCloak, if the realm that contains your client has more than one IDP configured, KeyCloak shows a page that prompts the user to select which IDP they want to log in with. Almost all teams have chosen to hide this page from their users by specifying the IDP as a query string parameter in the KeyCloak Authorization URI value behind their login button. The querystring is 'kc_idp_hint'. (The IDPs available will depend on the standard realm in which your client exists.) By specifying the IDP in this way, the user will be redirected directly to the login page for the identity provider and will not see the KeyCloak login choice page at all. + +| Display Name | kc_idp_hint | +| ------------- |:-------------:| +| IDIR | idir | +| Azure IDIR | azureidir | +| Basic BCeID | bceidbasic | +| Business BCeID | bceidbusiness | +| Basic or Business BCeID | bceidboth | +| GitHub BC Gov | githubbcgov | +| GitHub Public | githubpublic | + + +We do have a work around for those of you who ABSOLUTELY need the keycloak login page [here](https://github.com/bcgov/sso-keycloak/wiki/Recommend-Skipping-the-Keycloak-Login-Page-and-if-you-ABSOLUTELY-need-it), please talk to us about this. + +#### Do Validate the IDP in the JWT + +Because there are multiple IDPs available to your client in the standard realm, if your application has business logic that specifies a particular login method, you have to enforce that. For example, if your application requires BCeID to authenticate, you have to make sure that the user didn't somehow log in with IDIR instead. Your client has a mapper configured to provide the alias of the IDP that was used to log in. The name of the claim is 'identity_provider' and the possible aliases are the same as the ones that are used for the kc_idp_hint query parameter (see above). + +In the standard realms that support BCeID there are multiple IDPs (both BCeID and IDIR) and it is theoretically possible for a user to change the IDP hint (see above) maliciously using scripting or other techniques. Additionally, a user that is signed into another application that shares the same realm will get single sign-on with your app, so if you want to enforce a particular IDP, that's another good reason to validate the IDP that they used to sign in. It's up to you and your business logic requirements to make sure that your users have a good user experience and that you don't leave any room for unintended login flows. + +If for some reason you want to make sure that your users do NOT have a single sign-on experience, you can force them to re-authenticate according to the OIDC spec at: [3.1.2.3. Authorization Server Authenticates End-User](https://openid.net/specs/openid-connect-core-1_0.html#Authenticates). + +#### Do revoke tokens + +Ensure offline tokens are revoked after use or set the maximum time.     + +#### Do validate tokens at application level + +Validate the token at the application level rather than using an introspection endpoint + + +

+ +

+ +--- diff --git a/wiki/What-is-Keycloak-@-BC-Government?.md b/wiki/What-is-Keycloak-@-BC-Government?.md new file mode 100644 index 00000000..dc78a407 --- /dev/null +++ b/wiki/What-is-Keycloak-@-BC-Government?.md @@ -0,0 +1,39 @@ +# What is keycloak? +Keycloak is an open source Identity and Access Management solution aimed at modern applications and services. It makes it easy to secure applications and services with little to no code. [Keycloak - About](https://www.keycloak.org/) + +In BC Government, the Pathfinder SSO Keycloak server acts as an Open ID Connect [OIDC](https://openid.net/connect/) based Identity Provider, mediating with an enterprise user directory or 3rd-party SSO providers for identity information and applications via standards-based tokens and identity assertions. + + + + + +## As a digital delivery team, what do i need to know about Keycloak? + +Keycloak is organized by _realms_ which manages discrete sets of users that are logically isolated from one another and provides a linkage between the client application and a BC Government Identity Provider. + +BC Pathfinder SSO Clients are configured to be part of a Standard Realm where certain realm parameters can be configured by clients and users can only authenticate to the realm in which they belong. + +## Why a Standard Realm? +The KeyCloak product was not designed to handle an unlimited number of realms and we managed to find the limit (unfortunately!). + +New customers will now be added to one of the specially configured standard realms to help us continue to offer this great common component. + + + + + + +## Why a Custom Realm? + + +# Authentication vs Authorization + +[Useful terms can be found here](https://github.com/bcgov/sso-keycloak/wiki/Useful-References#intro-to-terms) + + +# Learn More +The Pathfinder SSO service is build on the foundations of Keycloak /Redhat SSO. + +* [Request an integration](https://bcgov.github.io/sso-requests/) +* [An overview of our CSS App](https://github.com/bcgov/sso-keycloak/wiki) +* [Additional References](https://github.com/bcgov/sso-keycloak/wiki/Useful-References) \ No newline at end of file diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md new file mode 100644 index 00000000..293a0af5 --- /dev/null +++ b/wiki/_Sidebar.md @@ -0,0 +1,18 @@ +# Getting Started + +- [Home](https://github.com/bcgov/sso-keycloak/wiki) +- [SSO Onboarding](https://github.com/bcgov/sso-keycloak/wiki/SSO-Onboarding) +- [Using Your SSO Client](https://github.com/bcgov/sso-keycloak/wiki/Using-Your-SSO-Client) +- [What is Keycloak @ BC Government](https://github.com/bcgov/sso-keycloak/wiki/What-is-Keycloak-@-BC-Government%3F) +- [Our Partners and Useful Info](https://github.com/bcgov/sso-keycloak/wiki/Our-Partners-and-Useful-Information) +- [Identity Provider Attribute Mapping](https://github.com/bcgov/sso-keycloak/wiki/Identity-Provider-Attribute-Mapping) +- [Handling Authorization/Create a Role](https://github.com/bcgov/sso-keycloak/wiki/Creating-a-Role) +- [Useful References](https://github.com/bcgov/sso-keycloak/wiki/Useful-References) +- [Pathfinder SSO Uptime](https://github.com/bcgov/sso-keycloak/wiki/Pathfinder-Uptime-Monitoring) +- [Our Service Level](https://github.com/bcgov/sso-keycloak/wiki/Alerts-and-Us#service-levels) + + +[![Semantic description of image](https://user-images.githubusercontent.com/87393930/133819035-4d0444b7-f962-4370-93b5-ac6201a05d0f.png)][2] + +[2]:https://github.com/bcgov/sso-keycloak/wiki/Additional-Help + diff --git a/wiki/index.md b/wiki/index.md new file mode 100644 index 00000000..4760fd30 --- /dev/null +++ b/wiki/index.md @@ -0,0 +1,118 @@ +# SSO Pathfinder Knowledge Base +>If you are intending to use the Pathfinder SSO service in order to provide authentication for your application, the SSO Pathfinder Knowledge Base is for you. You are in the right place. + +**>Get started now for your self serve experience to our [common hosted single sign on app](https://bcgov.github.io/sso-requests)** + +* [Standard Service](#standard-service) +* [Our Partners](#our-partners) +* [Benefits](#benefits) +* [More on our Standard Service](#more-on-our-standard-service) +* [Limitations](#limitations) +* [History](#history) +* [For Additional Help](https://github.com/bcgov/sso-keycloak/wiki/Additional-Help) +* [Placeholder on Custom Realms](#placeholder-on-custom-realms) + + +

+ +

+ + +
+ +
+ +#### *Have any questions? We would love to hear from you.* [![Semantic description of image](https://user-images.githubusercontent.com/87393930/133688357-09f82374-ba18-4402-8089-c0a989dde882.png)][2] + + + +[2]: https://chat.developer.gov.bc.ca/channel/sso +[3]: https://[mail](mailto:bcgov.sso@gov.bc.ca)[email](mailto:bcgov.sso@gov.bc.ca) + + + +## Standard Service + +The Pathfinder SSO service (also known as "KeyCloak" or "RedHat SSO") consists of two offerings: Standard and Custom. + +Over the years, we’ve engaged and learned that the majority of our clients can make use of our standard service, so we created the [Common hosted Single Sign on (CSS) App](https://bcgov.github.io/sso-requests/). It’s a simple way for application development teams to set up login functionality for their app from approved [identity providers](https://github.com/bcgov/sso-keycloak/wiki/Useful-References#identity-provider) over a standard and secure protocol aka to help you obtain the technical details for your login component. Learn more about [onboarding with us here](https://github.com/bcgov/sso-keycloak/wiki/SSO-Onboarding). + + +## Our Partners + +We provide our service with the support of our Identity Provider Partners. An "Identity Provider" is the holder of the identity that is used to log in with. [Learn more about our partners and relevant identity provider information](https://github.com/bcgov/sso-keycloak/wiki/Our-Partners-and-Useful-Information). + +Note: It is totally possible for your application to integrate with any or all of the identity providers directly instead of using the Pathfinder SSO service. + + + + + +## Benefits + +Here’s some reasons as to why this might work for your digital product: + +- **Easy setup.** We've made this the #1 feature of this service. You can get your DEV, TEST, and PROD instances running against most of the available identity providers right away. The Pathfinder SSO service already has integrations to the following identity providers: + - IDIR (BC Common Logon Page) + - [Learn about Azure IDIR ](https://github.com/bcgov/sso-keycloak/wiki/Useful-References#azure-idir-and-idir---whats-the-difference) + - BCeID Basic (BC Common Logon Page) -- Allows login only with BCeID _Basic_ + - BCeID Business (BC Common Logon Page) -- Allows login only with BCeID _Business_ + - BCeID Basic & Business(BC Common Logon Page) -- Allows login with BCeID _Basic_ or BCeID _Business_ + - GitHub associated with BC Gov Org -- Allows login of GitHub BC Gov Org members + +- **OIDC protocol.** Where certain identity providers (BCeID in particular) support SAML protocol when used directly, Pathfinder SSO brokers the SAML connection and lets you use OIDC instead. OIDC is more common and simpler to set up in modern programming stacks. +- **Session Management.** Some identity providers don't offer advanced session management capabilities. + +- **High Availability Requirements.** The Pathfinder SSO service is working on a formal published service level agreements (see [BC Government SSO Service Definition](https://digital.gov.bc.ca/common-components/pathfinder-sso/). This service is available 24/7 with questions and answers addressed during business hours only. [Uptime Monitoring](https://github.com/bcgov/sso-keycloak/wiki/Pathfinder-Uptime-Monitoring) + +#### More on our Standard Service + +Our standard service makes use of one "standard" realm. When you complete a request in our [common hosted single sign on app](https://bcgov.github.io/sso-requests), you receive a pre-configured client inside an existing realm. + +* If you need authorization ie role based access controls, we allow for client level roles to be created. [Learn more](https://github.com/bcgov/sso-keycloak/wiki/Creating-a-Role) +* [Are you Part of GitHub BC Gov Org](https://github.com/bcgov/sso-keycloak/wiki/Are-you-part-of-the-GitHub-BC-Gov-Org-%3F) +* [Situations where you use our service](https://github.com/bcgov/sso-keycloak/wiki/Using-Your-SSO-Client#usecases) +* [If you need to interact with the CSS App in a RESTful way](https://github.com/bcgov/sso-keycloak/wiki/CSS-API-Account) +* [CSS APP my Teams](https://github.com/bcgov/sso-keycloak/wiki/CSS-App-My-Teams) +* [CSS APP valid redirect URI Format](https://github.com/bcgov/sso-keycloak/wiki/CSS-App-Valid-Redirect-URI-Format) +* [Gold Migration Q&A](https://github.com/bcgov/sso-keycloak/discussions/categories/gold-q-a) + +### Limitations +It is technically possible to integrate directly with the various identity providers instead of using SSO-KEYCLOAK(formerly OCP-SSO). Architectural reasons for direct integration include: + + +- **High Volume Expectations.** The service is shared by many dozens of applications. If one application starts sending millions of login requests, the service itself can experience service degradation which is felt by all the users of all the applications. Pathfinder SSO is managed on the OpenShift Platform and scales fluidly, but there are limits to the resources it can consume. +- **Unique Configuration Needs.** New customers no longer receive a dedicated realm where they can experiment and invent on top of the platform (see "What's Changed" below). +- **BC Services Card Integration Requirements.** Because of the high-security nature of the BC Services Card identity and the private information that is available in the context of a login, BCSC is not allowed to be shared between applications. In a dedicated realm the BCSC integration, once approved and configured by IDIM, can be set up. Since we are not offering dedicated realms at this time, teams that need to integrate with BCSC will need to find another solution (see [BC Services Card Integration](https://github.com/bcgov/sso-keycloak/wiki/Our-Partners-and-Useful-Information#bc-service-card-integration) for useful advice). + + +## Placeholder on Custom Realms +[Custom Realm ](https://github.com/bcgov/sso-keycloak/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms) + + +## History + +### 2022 +• In early 2022, we consulted with teams using our custom service and are working with them to migrate to our new keycloak instance. If you think you need our custom service, please be advised we will ask you a few questions as we do not take provisioning a new custom service lightly. Read more on the way we work with our [Custom Service/Custom Realm community](https://github.com/bcgov/sso-keycloak/wiki/Gold-Custom-Realm-Community-Ways-of-Working) + +• In mid 2022, we moved our services from the Platform Services Silver Openshift cluster to their Gold Openshift cluster. We have mechanism in place for disaster recovery and we are an enterprise service. We ensure that clients in our gold service have their service up 24/7. + + +### 2021 + +• In 2021, we offered clients the ability to integrate with our specially configured standard service. Instead of receiving an entire realm per team, they will receive a pre-configured client inside an existing realm. There is no compromise to the security in this configuration, but it does mean that teams will no longer receive credentials to log on to the KeyCloak server and make changes to their configuration. Changes will be made by the operations team in response to requests for now (we're working on automations to solve this problem). Although this is a compromise in terms of the flexibility of the service, it actually makes setting up simpler and faster for teams. + +### 2016-2019 + +• Customers were provisioned their very own KeyCloak realm. A realm is like a security zone that is protected from the configuration changes made by other realms. Each team worked in their own realm and was given access to the KeyCloak administration console for their realm where they could make any changes they wanted to. We call this our "custom service". + +• In 2020, the SSO-KEYCLOAK(formerly OCP-SSO) service started to hit maximum capacity for realms in a way that was not possible to mitigate via the usual vertical and horizontal scaling approaches. The KeyCloak product was not designed to handle an unlimited number of realms and we managed to find the limit (unfortunately!) + + +-------------------- + + +