From 2aeda6bb6ae2a725fa00303eb24217a90a6c18dc Mon Sep 17 00:00:00 2001 From: jonathan langlois Date: Wed, 22 Nov 2023 15:18:21 -0800 Subject: [PATCH] chore: precommit install and run pre-commit --- README.md | 2 +- catalog-info.yaml | 2 +- mkdocs.yml | 4 +-- wiki/Additional-Help.md | 1 - wiki/Alerts-and-Us.md | 28 +++++++++---------- .../Are-you-part-of-the-GitHub-BC-Gov-Org?.md | 9 +----- wiki/CSS-API-Account.md | 2 +- wiki/CSS-App-My-Teams.md | 13 ++++----- wiki/CSS-App-Valid-Redirect-URI-Format.md | 2 +- wiki/Creating-a-Role.md | 8 +++--- ...-Custom-Realm-Community-Ways-of-Working.md | 4 +-- wiki/Identity-Provider-Attribute-Mapping.md | 2 +- wiki/Our-Partners-and-Useful-Information.md | 10 +++---- wiki/Pathfinder-Uptime-Monitoring.md | 6 ++-- ...ogin-Page-and-if-you-ABSOLUTELY-need-it.md | 4 +-- ...to-delete-a-custom-Pathfinder-SSO-Realm.md | 4 +-- wiki/SSO-Onboarding.md | 7 ++--- wiki/SSO-Pathfinder-Knowledge-Base.md | 2 +- ...ence-Between-Custom-and-Standard-Realms.md | 2 +- wiki/Useful-References.md | 11 ++++---- wiki/Using-Your-SSO-Client.md | 20 ++++++------- wiki/What-is-Keycloak-@-BC-Government?.md | 4 +-- wiki/_Sidebar.md | 1 - wiki/index.md | 23 +++++++-------- 24 files changed, 75 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index a6142b3c..ab645890 100644 --- a/README.md +++ b/README.md @@ -17,4 +17,4 @@ Devhub docs are generated using [mkdocs](https://www.mkdocs.org/getting-started/ _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 +Then run `mkdocs serve` to see the site locally. diff --git a/catalog-info.yaml b/catalog-info.yaml index a17c75ad..6d59e3b8 100644 --- a/catalog-info.yaml +++ b/catalog-info.yaml @@ -9,4 +9,4 @@ metadata: spec: type: documentation lifecycle: production - owner: "citz" \ No newline at end of file + owner: "citz" diff --git a/mkdocs.yml b/mkdocs.yml index d3980ea6..d031d801 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: BC Gov Common Hosted Single Sign-on docs_dir: wiki -plugins: -- techdocs-core \ No newline at end of file +plugins: +- techdocs-core diff --git a/wiki/Additional-Help.md b/wiki/Additional-Help.md index b82cd56a..6b5374c4 100644 --- a/wiki/Additional-Help.md +++ b/wiki/Additional-Help.md @@ -12,4 +12,3 @@ Within RocketChat if you see someone asking questions or have issues for which y

- diff --git a/wiki/Alerts-and-Us.md b/wiki/Alerts-and-Us.md index 9ff9be23..45c35824 100644 --- a/wiki/Alerts-and-Us.md +++ b/wiki/Alerts-and-Us.md @@ -7,14 +7,14 @@ Our service, the Pathfinder SSO ensures that our Keycloak server acts as an Open Specifically, we make use of the Red Hat SSO v 7.6.1.GA -**Other systems we rely on** +**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). +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%. @@ -23,7 +23,7 @@ Reference: [Private Cloud Memorandum of Understanding](https://cloud.gov.bc.ca/p **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. +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%. @@ -53,7 +53,7 @@ This is SLA is is based on the highest SLA for the services we rely on. #### 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 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 @@ -67,11 +67,11 @@ The Pathfinder SSO Team responds to 3 levels or incidents: P1 - Critical, P3 - M 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) @@ -80,11 +80,11 @@ It should be noted that our current version of Redhat SSO does not enable us to **Change Communications** -When a change occurs on our service, we will provide notification in advance in these ways: +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. +**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. @@ -120,7 +120,7 @@ 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 +### Gold Keycloak SSO Prod End User Access Uptime | Month | Downtime | | -------- | ------- | | January 2023 | 41m 6s | @@ -134,7 +134,7 @@ Uptime will calculate the total downtime for the alert | September 2023 | 0 | | October 2023 | 0h27m2s | -### Gold KeyCloak SSO Prod and IDIR siteminder Uptime +### Gold KeyCloak SSO Prod and IDIR siteminder Uptime | Month | Downtime | | -------- | ------- | | January 2023 | 1h0m18s | @@ -152,7 +152,7 @@ Uptime will calculate the total downtime for the alert ### 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 +##### P1 Stats | Month | Number of Alerts | Acknowledge Time | Resolve Time | Notes | | :--- | :----: | :----: | ---: |---: | | January | 6 | 2min 11s | 45m 26s | Jan 25 & Jan 24 - OCP Upgrade | @@ -182,7 +182,7 @@ Pathfinder Team commits to acknowledging issue within 15 -30 mins and resolving | 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 -- +#### 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 | @@ -238,5 +238,3 @@ TBD | 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 index 8939365f..7119e8c5 100644 --- a/wiki/Are-you-part-of-the-GitHub-BC-Gov-Org?.md +++ b/wiki/Are-you-part-of-the-GitHub-BC-Gov-Org?.md @@ -1,14 +1,7 @@ -You have been redirected to this page because your github account is not affiliated with the organization `bcgov`. +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 index 3e232134..241a1f0a 100644 --- a/wiki/CSS-API-Account.md +++ b/wiki/CSS-API-Account.md @@ -35,4 +35,4 @@ A: No, your CSS API Account is used only to manage your team's gold integrations 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 +A: You can request CSS API Account even if there are no integrations associated with your team diff --git a/wiki/CSS-App-My-Teams.md b/wiki/CSS-App-My-Teams.md index fbf3b725..e10b89ee 100644 --- a/wiki/CSS-App-My-Teams.md +++ b/wiki/CSS-App-My-Teams.md @@ -1,13 +1,13 @@ # 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. +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. +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 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. @@ -37,11 +37,11 @@ When creating a team, you can assign this team to one integration, or several in #### Managing a team as an Admin -Users with the **Admin** role can manage teams. +Users with the **Admin** role can manage teams. -##### Adding New Team Members: +##### Adding New Team Members: -**Admins** can add new users to a Team, and assign users as either Admins or 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. @@ -92,4 +92,3 @@ Only an **Admin** can create roles and once the roles are created, Admins and Me | 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 index 35a3fb9b..ccf48f84 100644 --- a/wiki/CSS-App-Valid-Redirect-URI-Format.md +++ b/wiki/CSS-App-Valid-Redirect-URI-Format.md @@ -6,4 +6,4 @@ In CSS app, the allowed URI syntax consists of two parts with `://` in the middl - `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 +* We made an exception to allow wildcard (*) in the dev, and test environments to satisfy the various development processes. diff --git a/wiki/Creating-a-Role.md b/wiki/Creating-a-Role.md index 1f416069..b74486b0 100644 --- a/wiki/Creating-a-Role.md +++ b/wiki/Creating-a-Role.md @@ -10,7 +10,7 @@ Roles identify a type or category of user. Admin, user, manager, and employee ar 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? +### 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. @@ -26,7 +26,7 @@ You can use roles to enable access to specific pages or data to only those users [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. - @@ -49,7 +49,7 @@ You can use roles to enable access to specific pages or data to only those users 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 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) @@ -62,7 +62,7 @@ Some client teams require roles to be created for their service accounts. Exampl 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" +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 index 500dccf6..33662f66 100644 --- a/wiki/Gold-Custom-Realm-Community-Ways-of-Working.md +++ b/wiki/Gold-Custom-Realm-Community-Ways-of-Working.md @@ -1,2 +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 +Please visit our updated material here +https://bcgov.github.io/sso-docs/best-practices/gold-way-work diff --git a/wiki/Identity-Provider-Attribute-Mapping.md b/wiki/Identity-Provider-Attribute-Mapping.md index c2a37946..931bf614 100644 --- a/wiki/Identity-Provider-Attribute-Mapping.md +++ b/wiki/Identity-Provider-Attribute-Mapping.md @@ -9,4 +9,4 @@ [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 +[Try our playground to see what comes in the payload with your client integration](https://bcgov.github.io/keycloak-example-apps/) diff --git a/wiki/Our-Partners-and-Useful-Information.md b/wiki/Our-Partners-and-Useful-Information.md index ea716271..6e1865f7 100644 --- a/wiki/Our-Partners-and-Useful-Information.md +++ b/wiki/Our-Partners-and-Useful-Information.md @@ -23,13 +23,13 @@ - **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) +- **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. +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 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) @@ -40,7 +40,7 @@ Also note if you get an error message similar to the one below, please ensure th ### 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. +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. @@ -50,7 +50,7 @@ Please ensure you have tested with an incognito browser as mentioned above. If i ## Digital Credential Configuration -This defines which credential (or combinations of credentials) will be requested at user authentication. +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) diff --git a/wiki/Pathfinder-Uptime-Monitoring.md b/wiki/Pathfinder-Uptime-Monitoring.md index 02a2e538..fa790690 100644 --- a/wiki/Pathfinder-Uptime-Monitoring.md +++ b/wiki/Pathfinder-Uptime-Monitoring.md @@ -3,7 +3,7 @@ * [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 +## 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) @@ -22,7 +22,7 @@ We know in advance the week Gold work will happen. Will notify community members ## 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. +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 @@ -41,4 +41,4 @@ Going from our primary to fail over is something we are prepared for. You can ex * 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 +* The priority of this service is to maximize availability to the end users and automation. 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 index e858b276..606c69ac 100644 --- 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 @@ -1,6 +1,6 @@ # 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 +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. @@ -18,5 +18,3 @@ If you are a client of ours and have an **absolute** need to have a dedicated se [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 index 01286ffb..73051d05 100644 --- a/wiki/Request-to-delete-a-custom-Pathfinder-SSO-Realm.md +++ b/wiki/Request-to-delete-a-custom-Pathfinder-SSO-Realm.md @@ -1,5 +1,5 @@ -As of July 2023 this is archived information that will be ressurected once our gold custom realm registry is created. +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? @@ -21,4 +21,4 @@ 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 +Please note that we will only start processing your request when the you've reached out us. diff --git a/wiki/SSO-Onboarding.md b/wiki/SSO-Onboarding.md index ed2ef737..5cac72ff 100644 --- a/wiki/SSO-Onboarding.md +++ b/wiki/SSO-Onboarding.md @@ -14,9 +14,9 @@ Use the [Common hosted Single Sign on 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. +Please note the provisioning process is the same as IDIR. -### Need to host your application on the BC Gov Cloud service? +### Need to host your application on the BC Gov Cloud service? Please visit [BCGov Cloud Services](https://digital.gov.bc.ca/cloud/services/) @@ -27,6 +27,3 @@ Once you have your client details, you can configure your application to use the #### *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 index f7f6f9b7..4d10ce20 100644 --- a/wiki/SSO-Pathfinder-Knowledge-Base.md +++ b/wiki/SSO-Pathfinder-Knowledge-Base.md @@ -1 +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 +> ### We are working to improve this flow and in the interim please visit our [wiki](https://github.com/bcgov/sso-keycloak/wiki) diff --git a/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms.md b/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms.md index c5c9983f..1d3a2ff4 100644 --- a/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms.md +++ b/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms.md @@ -1,3 +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 +![](https://github.com/bcgov/sso-realm-registry/blob/dev/app/public/home-right.png) diff --git a/wiki/Useful-References.md b/wiki/Useful-References.md index 9bab8c84..70beccef 100644 --- a/wiki/Useful-References.md +++ b/wiki/Useful-References.md @@ -11,7 +11,7 @@ ## Intro to terms -### Authentication +### Authentication Authentication is the process of verifying who someone is @@ -20,13 +20,13 @@ Authentication is the process of verifying who someone is 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 +### 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) +### [Keycloak how we describe it](https://github.com/bcgov/sso-keycloak/wiki/What-is-Keycloak-@-BC-Government%3F#what-is-keycloak) ### Newbie Guide @@ -68,13 +68,12 @@ The following links are a good introduction or refresher to the OIDC standard. [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 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) +[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 index 96110dc8..a7e06a41 100644 --- a/wiki/Using-Your-SSO-Client.md +++ b/wiki/Using-Your-SSO-Client.md @@ -44,7 +44,7 @@ Visit our [discussions page](https://github.com/bcgov/sso-keycloak/discussions/1 ### 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) +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 @@ -58,11 +58,11 @@ For Red Hat SSO & Keycloak version information, please see this link: https://ac ### 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. +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. +For IDIR and GitHub, your users will use "real" credentials in all three environments. ##### BCeID Accounts @@ -89,7 +89,7 @@ All clients of Pathfinder SSO will use _Authorization Code Flow_. This is the mo 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. +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. @@ -112,7 +112,7 @@ If not using the adapter, you can use a custom implementation. This will require 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 +#### Usecases **Browser Login** - A web based application requiring a login component @@ -190,7 +190,7 @@ After having your `Installation JSON`, you can setup your application quickly us #### 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. +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. @@ -203,7 +203,7 @@ These are: - **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 +##### OpenID Provider Metadata sample It gives you `OpenID Provider Metadata` required for the OpenID connect configration: ```json @@ -296,8 +296,8 @@ Your redirect URIs should only be resources that you control. Most of the time y 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 | -| ------------- |:-------------:| +| Display Name | kc_idp_hint | +| ------------- |:-------------:| | IDIR | idir | | Azure IDIR | azureidir | | Basic BCeID | bceidbasic | @@ -307,7 +307,7 @@ In KeyCloak, if the realm that contains your client has more than one IDP config | 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. +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 diff --git a/wiki/What-is-Keycloak-@-BC-Government?.md b/wiki/What-is-Keycloak-@-BC-Government?.md index dc78a407..8c659416 100644 --- a/wiki/What-is-Keycloak-@-BC-Government?.md +++ b/wiki/What-is-Keycloak-@-BC-Government?.md @@ -2,7 +2,7 @@ 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. - + @@ -36,4 +36,4 @@ 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 +* [Additional References](https://github.com/bcgov/sso-keycloak/wiki/Useful-References) diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index 293a0af5..0019ff76 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -15,4 +15,3 @@ [![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 index 4760fd30..e49b2479 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -1,5 +1,5 @@ -# 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. +# 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)** @@ -36,7 +36,7 @@ ## Standard Service -The Pathfinder SSO service (also known as "KeyCloak" or "RedHat SSO") consists of two offerings: Standard and Custom. +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). @@ -55,13 +55,13 @@ Note: It is totally possible for your application to integrate with any or all o 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) +- **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 + - 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. @@ -70,12 +70,12 @@ Here’s some reasons as to why this might work for your digital product: #### 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. +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) +* [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) @@ -85,11 +85,11 @@ It is technically possible to integrate directly with the various identity provi - **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). +- **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 +## Placeholder on Custom Realms [Custom Realm ](https://github.com/bcgov/sso-keycloak/wiki/Understanding-the-Difference-Between-Custom-and-Standard-Realms) @@ -113,6 +113,3 @@ It is technically possible to integrate directly with the various identity provi -------------------- - - -