Commit cbbafd5b authored by Ondrej Vojtisek's avatar Ondrej Vojtisek
Browse files

Fork from cbioportal oficial git repo

parent 965ae7b8
The cBioPortal for Cancer Genomics was originally developed at [Memorial Sloan Kettering Cancer Center](http://www.mskcc.org/) (MSK). The [public cBioPortal site](http://cbioportal.org) is hosted by the [Center for Molecular Oncology](http://www.mskcc.org/research/molecular-oncology) at MSK. The cBioPortal software is now available under an open source license via [GitHub](https://github.com/cBioPortal/cbioportal/). The software is now developed and maintained by a multi-institutional team, consisting of MSK, the Dana Farber Cancer Institute, Princess Margaret Cancer Centre in Toronto, Children's Hospital of Philadelphia, The Hyve in the Netherlands, and Bilkent University in Ankara, Turkey.
This instance of cBioPortal is under administration of [EurOPDX consortium](http://europdx.eu/).
The cBioPortal for Cancer Genomics was originally developed at [Memorial Sloan Kettering Cancer Center](http://www.mskcc.org/) (MSK). The [public cBioPortal site](http://cbioportal.org) is hosted by the [Center for Molecular Oncology](http://www.mskcc.org/research/molecular-oncology) at MSK. The cBioPortal software is now available under an open source license via [GitHub](https://github.com/cBioPortal/cbioportal/). The software is now developed and maintained by a multi-institutional team, consisting of MSK, the Dana Farber Cancer Institute, Princess Margaret Cancer Centre in Toronto, Children's Hospital of Philadelphia, [The Hyve](http://thehyve.nl) in the Netherlands, and Bilkent University in Ankara, Turkey.
## Memorial Sloan Kettering Cancer Center
* Jianjiong Gao
......@@ -11,24 +9,26 @@ This instance of cBioPortal is under administration of [EurOPDX consortium](http
* Adam Abeshouse
* Ritika Kundra
* Ino de Bruijn
* Zachary Heins
* Robert Sheridan
* Angelica Ochoa
* Aaron Lisman
* Manda Wilson
* Jiaojiao Wang
* Avery Wang
* Nikolaus Schultz
## Dana-Farber Cancer Institute
* Ethan Cerami
* Ersin Ciftci
* Tali Mazor
* Augustin Luna
* James Lindsay
* Priti Kumari
* Catherine Del Vecchio
* Andy Dufilie
* Chris Sander
## Princess Margaret Cancer Centre, Toronto
* Stuart Watt
* Kelsey Zhu
* Trevor Pugh
## Children's Hospital of Philadelphia
......@@ -40,22 +40,22 @@ This instance of cBioPortal is under administration of [EurOPDX consortium](http
## The Hyve
* Pieter Lukasse
* Fedde Schaeffer
* Sander Tan
* Oleguer Plantalech
* Irina Pulyakhina
* Riza Nugraha
* Dionne Zaal
* Sjoerd van Hagen
* Sander de Ridder
* Kees van Bochove
## Bilkent University
* Ugur Dogrusoz
* Istemi Bahceci
* M. Furkan Sahin
* Leonard Dervishi
## Weill Cornell Medicine
* Alexandros Sigaras
* Ken Eng
* Andrea Sboner
* Olivier Elemento
* Mark Rubin
* Lewis Cantley
## Alumni
* B. Arman Aksoy
......@@ -63,28 +63,35 @@ This instance of cBioPortal is under administration of [EurOPDX consortium](http
* Hsiao-Wei Chen
* Fred Criscuolo
* Gideon Dresdner
* Andy Dufilie
* Arthur Goldberg
* Zachary Heins
* Michael Heuer
* Anders Jacobsen
* Erik Larsson
* Dong Li
* Tamba Monrose
* Peter Kok
* M. Furkan Sahin
* Stuart Watt
* James Xu
## Funding for the cBioPortal for Cancer Genomics is or has been provided by:
### Current:
* ITCR, through a [U24 grant](https://itcr.nci.nih.gov/funded-project/cbioportal-cancer-genomics) (NCI-U24CA220457)
* Marie-José and Henry R. Kravis Center for Molecular Oncology at MSK
* Dana Farber Cancer Institute
* Robertson Foundation
* American Association for Cancer Research through AACR Project GENIE
* POETIC Consortium
* Prostate Cancer Foundation
* Breast Cancer Research Foundation
* Adenoid Cystic Carcinoma Research Foundation
* Robertson Foundation
### Past:
* Stand Up 2 Cancer
* American Association for Cancer Research (AACR) through Project GENIE
* The Ben & Catherine Ivy Foundation
* NCI, as a [TCGA Genome Data Analysis Center (GDAC)](http://tcga.cancer.gov/wwd/program/research_network/gdac.asp) (NCI-U24CA143840)
* NCRR, as the [National Resource for Network Biology (NRNB)](http://nrnb.org/) Research Resource (RR 031228-02)
* Starr Cancer Consortium
\ No newline at end of file
* Starr Cancer Consortium
* Breast Cancer Research Foundation
* Adenoid Cystic Carcinoma Research Foundation
* Prostate Cancer Foundation
# Introduction
The cBioPortal includes support for LDAP authentication. This document explains how to configure LDAP within your own instance of cBioPortal.
Configuring your local instance to support LDAP requires a few configuration changes.
## Overview
In this setup LDAP will be used as a simple Identity Provider (IDP) for the authentication.
* **identity provider**: in this scenario, it can be limited to a service that stores user names and passwords, and provides an authentication mechanism.
* **service provider**: any web site or web application that provides a service, but should only be available to authenticated and authorized users. In the documentation below, the cBioPortal is the service provider.
* **authentication**: a means of verifying that a user is who they purport to be. Authentication is performed by the identify provider, by extracting the user name and password provided in a login request, and matching this with information stored in its repository.
* **authorization**: defines resources a user can access. When authorization is turned *on* with cBioPortal, users can only access cancer studies they are specifically authorized to view. This enables one to store multiple cancer studies within a single instance of cBioPortal, but provide fine-grained control over which users can access which studies. Authorization is implemented within the core cBioPortal code, and *not* the identify provider.
## Why is LDAP Relevant to cBioPortal?
The cBioPortal code has no means of storing user name and passwords and no means of directly authenticating users. If you want to restrict access to your instance of cBioPortal, you therefore have to consider an external authentication service. LDAP is one means of doing so, and your larger institution may already provide LDAP support. This greatly simplifies user management.
# Configuring LDAP within cBioPortal
## Modifying portal.properties
Within portal.properties, modify the section labeled `authentication`. For example:
# authentication
authenticate=ldap
## configuration for the LDAP access
ldap.user_search_base=DC=example,DC=com
ldap.url=ldap://ldap.example.com:389
ldap.manager.dn=
ldap.manager.password=
## The following attributes for are good for ActiveDirectory, for OpenLDAP use "uid" for username
ldap.attributes.username=sAMAccountName
#ldap.attributes.username=uid
ldap.attributes.last_name=sn
ldap.attributes.given_name=givenName
ldap.attributes.email=mail
Please note that you will have to modify all the above to match your own settings. Also note, in most cases ldap.manager.dn and ldap.manager.password should be left empty, although the properties should remain in portal.properties.
## Authorizing Users
Within portal.properties, modify
authorization=true
Next, please read the Wiki page on [User Authorization](User-Authorization.md), and add user rights for a single user.
## Configuring the Login.jsp Page
The login page is configurable via the `portal.properties` properties `skin.authorization_message`.
For example in `skin.authorization_message` you can be set to something like this:
```
skin.authorization_message= Welcome to this portal. Access to this portal is available to authorized test users at YOUR ORG. [<a href="http://thehyve.nl/">Request Access</a>].
```
You can also set a standard text in `skin.login.contact_html` that will appear in case of problems:
```
skin.login.contact_html=If you think you have received this message in error, please contact us at <a style="color:#FF0000" href="mailto:cbioportal-access@your.org">cbioportal-access@your.org</a>
```
## Doing a Test Run
You are now ready to go.
Rebuild the WAR file and re-deploy:
```
mvn -DskipTests clean install
cp portal/target/cbioportal.war $CATALINA_HOME/webapps/
```
Then, go to: [http://localhost:8080/cbioportal/](http://localhost:8080/cbioportal/).
If all goes well, the following should happen:
* You will be redirected to the Login Page.
* After authenticating, you will be redirected the home page.
Example of Login page:
![Login page example](images/previews/login_page_example.png)
If this does not happen, see the Troubleshooting Tips below.
## Troubleshooting Tips
### Logging
If you get stuck or get an obscure error message, you can try to turn on all DEBUG logging. This can be done via `src/main/resources/log4j.properties`. For example:
# Change INFO to DEBUG, if you want to see debugging info on underlying libraries we use.
log4j.rootLogger=DEBUG, a
# Change INFO to DEBUG, if you want see debugging info on our packages only.
log4j.category.org.mskcc=DEBUG
Then, rebuild the WAR, redeploy, and try to authenticate again.
# Introduction
The cBioPortal includes support for SAML (Security Assertion Markup Language). This document explains why you might find SAML useful, and how to configure SAML within your own instance of cBioPortal.
Please note that configuring your local instance to support SAML requires many steps. This includes configuration changes and a small amount of debugging. If you follow the steps below, you should be up and running relatively quickly, but be forewarned that you may have do a few trial runs to get everything working.
In the documentation below, we also provide details on how to perform SAML authentication via a commercial company: [OneLogin](https://www.onelogin.com/). OneLogin provides a free tier for testing out SAML authentication, and is one of the easier options to get a complete SAML workflow set-up. Once you have OneLogin working, you should then have enough information to transition to your final authentication service.
## What is SAML?
SAML is an open standard that enables one to more easily add an authentication service on top of any existing web application. For the full definition, see the [SAML Wikipedia entry](http://en.wikipedia.org/wiki/Security_Assertion_Markup_Language).
In its simplest terms, SAML boils down to four terms:
* **identity provider**: this is a web-based service that stores user names and passwords, and provides a login form for users to authenticate. Ideally, it also provides easy methods to add / edit / delete users, and also provides methods for users to reset their password. In the documentation below, OneLogin.com serves as the identity provider.
* **service provider**: any web site or web application that provides a service, but should only be available to authenticated and authorized users. In the documentation below, the cBioPortal is the service provider.
* **authentication**: a means of verifying that a user is who they purport to be. Authentication is performed by the identify provider, by extracting the user name and password provided in a login form, and matching this with information stored in a database.
* **authorization**: defines resources a user can access. When authorization is turned on with cBioPortal, users can only access cancer studies they are specifically authorized to view (or PUBLIC studies, [if the server has been configured to contain these](User-Authorization.md#configuring-public-studies)). This enables one to store multiple cancer studies within a single instance of cBioPortal, but provide fine-grained control over which users can access which studies. Authorization is implemented within the core cBioPortal code, and not the identify provider.
## Why is SAML Relevant to cBioPortal?
The cBioPortal code has no means of storing user name and passwords and no means of directly authenticating users. If you want to restrict access to your instance of cBioPortal, you therefore have to consider an external authentication service. SAML is one means of doing so, and your larger institution may already provide SAML support. For example, at Sloan Kettering and Dana-Farber, users of the internal cBioPortal instances login with their regular credentials via SAML. This greatly simplifies user management.
# Setting up an Identity Provider
As noted above, we provide details on how to perform SAML authentication via a commercial company: [OneLogin](https://www.onelogin.com/).
If you already have an IDP set up, you can skip this part and go to [Configuring SAML within cBioPortal](#configuring-saml-within-cbioportal).
OneLogin provides a free tier for testing out SAML authentication, and is one of the easier options to get a complete SAML workflow set-up. Once you have OneLogin working, you should then have enough information to transition to your final authentication service. As you follow the steps below, the following link may be helpful: [How to Use the OneLogin SAML Test Connector](https://support.onelogin.com/hc/en-us/articles/202673944-How-to-Use-the-OneLogin-SAML-Test-Connector).
To get started:
* [Register a new OneLogin.com Account](https://www.onelogin.com/signup?ref=floating-sidebar)
## Setting up a SAML Test Connector
* [Login to OneLogin.com](https://app.onelogin.com/login).
* Under Apps, Select Add Apps.
* Search for SAML.
* Select the option labeled: OneLogin SAML Test (IdP w/attr).
* "SAVE" the app, then select the Configuration Tab.
* Under the Configuration Tab for OneLogin SAML Test (IdP w/attr), paste the following fields (this is assuming you are testing everything via localhost).
* Audience: cbioportal
* Recipient: http://localhost:8080/cbioportal/saml/SSO
* ACS (Consumer) URL Validator*: ^http:\/\/localhost\:8080\/cbioportal\/saml\/SSO$
* ACS (Consumer) URL*: http://localhost:8080/cbioportal/saml/SSO
![](images/previews/onelogin-config.png)
* Add at least the parameters:
* Email (Attribute)
* Email (SAML NameID)
![](images/previews/onelogin-config-parameters.png)
* Find your user in the "Users" menu
![](images/previews/onelogin-users-search.png)
* Link the SAML app to your user (click "New app" on the **+** icon found on the top right of the "Applications" table to do this - see screenshot below):
![](images/previews/onelogin-add-app.png)
* Configure these **email** parameters in the Users menu:
![](images/previews/onelogin-users.png)
## Downloading the SAML Test Connector Meta Data
* Go to the SSO Tab within OneLogin SAML Test (IdP), find the field labeled: Issuer URL. Copy this URL and download it's contents. This is an XML file that describes the identity provider.
![](http://f.cl.ly/items/1R0v0L3P1U2E23202V1d/Image%202015-05-24%20at%2010.07.56%20PM.png)
then, move this XML file to:
portal/src/main/resources/
You should now be all set with OneLogin.com. Next, you need to configure your instance of cBioPortal.
# Configuring SAML within cBioPortal
## Creating a KeyStore
In order to use SAML, you must create a [Java Keystore](http://docs.oracle.com/javase/7/docs/api/java/security/KeyStore.html).
This can be done via the Java `keytool` command, which is bundled with Java.
Type the following:
keytool -genkey -alias secure-key -keyalg RSA -keystore samlKeystore.jks
This will create a Java keystore for a key called: `secure-key` and place the keystore in a file named `samlKeystore.jks`. You will be prompted for:
* keystore password (required, for example: apollo1)
* your name, organization and location (optional)
* key password for `secure-key` (required, for example apollo2)
When you are done, copy `samlKeystore.jsk` to the correct location:
mv samlKeystore.jks portal/src/main/resources/
If you need to export the public certificate associated within your keystore, run:
keytool -export -keystore samlKeystore.jks -alias secure-key -file cBioPortal.cer
##### HTTPS and Tomcat
:warning: If you already have an official (non-self-signed) SSL certificate, and need to get your site
running on HTTPS directly from Tomcat, then you need to import your certificate into the keystore instead.
See [this Tomcat documentation page](https://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html) for more details.
:warning: An extra warning for when configuring HTTPS for Tomcat: use the same password for
both keystore and secure-key. This seems to be an extra restriction by Tomcat.
## Modifying portal.properties
Within portal.properties, make sure that:
app.name=cbioportal
Then, modify the section labeled `authentication`. See SAML parameters shown in example below:
# authentication
authenticate=saml
authorization=true
saml.sp.metadata.entityid=cbioportal
saml.idp.metadata.location=classpath:/onelogin_metadata_620035.xml
saml.idp.metadata.entityid=https://app.onelogin.com/saml/metadata/620035
saml.keystore.location=classpath:/samlKeystore.jks
saml.keystore.password=apollo1
saml.keystore.private-key.key=secure-key
saml.keystore.private-key.password=apollo2
saml.keystore.default-key=secure-key
saml.idp.comm.binding.settings=defaultBinding
saml.idp.comm.binding.type=
saml.idp.metadata.attribute.email=User.email
saml.custom.userservice.class=org.cbioportal.security.spring.authentication.saml.SAMLUserDetailsServiceImpl
# global logout (as opposed to local logout):
saml.logout.local=false
saml.logout.url=/
Please note that you will have to modify all the above to match your own settings. `saml.idp.comm.binding.type` can be left empty if `saml.idp.comm.binding.settings=defaultBinding`. The `saml.logout.*` settings above reflect the settings of an IDP that supports Single Logout (hopefully the default in most cases - more details in section below).
### Custom scenarios
:information_source: Some settings may need to be adjusted to non-default values, depending on your IDP. For example, if your
IDP required HTTP-GET requests instead of HTTP-POST, you need to set these properties as such:
saml.idp.comm.binding.settings=specificBinding
saml.idp.comm.binding.type=bindings:HTTP-Redirect
If you need a very different parsing of the SAML tokens than what is done at `org.cbioportal.security.spring.authentication.saml.SAMLUserDetailsServiceImpl`, you can point the `saml.custom.userservice.class` to your own implementation:
saml.custom.userservice.class=<your_package.your_class_name>
:warning: The property `saml.idp.metadata.attribute.email` can also vary per IDP. It is important to set this correctly since this is a required field by the cBioPortal SAML parser (that is, if `org.cbioportal.security.spring.authentication.saml.SAMLUserDetailsServiceImpl` is chosen for property `saml.custom.userservice.class`).
:warning: Some IDPs like to provide their own logout page (e.g. when they don't support the custom SAML Single Logout protocol). For this you can adjust the
`saml.logout.url` property to a custom URL provided by the IDP. Also set the `saml.logout.local=true` property in this case to indicate that global logout (or Single Logout) is not supported by IDP:
# local logout followed by a redirect to a global logout page:
saml.logout.local=true
saml.logout.url=<idp specific logout URL, e.g. https://idp.logoutpage.com >
## More customizations
If your IDP does not have the flexibility of sending the specific credential fields expected by our
default "user details parsers" implementation (i.e. `security/security-spring/src/main/java/org/cbioportal/security/spring/authentication/saml/SAMLUserDetailsServiceImpl.java`
expects field `mail` to be present in the SAML credential), then please let us know via a [new
issue at our issue tracking system](https://github.com/cBioPortal/cbioportal/issues/new), so we can
evaluate whether this is a scenario we would like to support in the default code. You can also consider
adding your own version of the `SAMLUserDetailsService` class.
## Authorizing Users
Next, please read the Wiki page on [User Authorization](User-Authorization.md), and add user rights for a single user.
## Configuring the Login.jsp Page (not applicable to most external IDPs)
The login page is configurable via the `portal.properties` properties `skin.authorization_message` and `skin.login.saml.registration_htm`.
For example in `skin.authorization_message` you can be set to something like this:
```
skin.authorization_message= Welcome to this portal. Access to this portal is available to authorized test users at YOUR ORG. [<a href="http://thehyve.nl/">Request Access</a>].
```
and `skin.login.saml.registration_htm` can be set to:
```
skin.login.saml.registration_htm=Sign in via XXXX
```
You can also set a standard text in `skin.login.contact_html` that will appear in case of problems:
```
skin.login.contact_html=If you think you have received this message in error, please contact us at <a style="color:#FF0000" href="mailto:cbioportal-access@your.org">cbioportal-access@your.org</a>
```
## Doing a Test Run
You are now ready to go.
Rebuild the WAR file and re-deploy:
```
mvn -DskipTests clean install
cp portal/target/cbioportal.war $CATALINA_HOME/webapps/
```
Then, go to: [http://localhost:8080/cbioportal/](http://localhost:8080/cbioportal/).
If all goes well, the following should happen:
* You will be redirected to the OneLogin Login Page.
* After authenticating, you will be redirected back to your local instance of cBioPortal.
If this does not happen, see the Troubleshooting Tips below.
## Troubleshooting Tips
### Logging
Getting this to work requires many steps, and can be a bit tricky. If you get stuck or get an obscure error message, your best bet is to turn on all DEBUG logging. This can be done via `src/main/resources/log4j.properties`. For example:
```
# Change INFO to DEBUG, if you want to see debugging info on underlying libraries we use.
log4j.rootLogger=DEBUG, a
# Change INFO to DEBUG, if you want see debugging info on our packages and spring security packages.
log4j.category.org.mskcc=DEBUG
log4j.logger.org.springframework.security=DEBUG
```
Then, rebuild the WAR, redeploy, and try to authenticate again. Your log file will then include hundreds of SAML-specific messages, even the full XML of each SAML message, and this should help you debug the error.
### Seeing the SAML messages
Another tool we can use to troubleshoot is SAML tracer (https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/ ). You can add this to Firefox and it will give you an extra menu item in "Tools". Go through the loging steps and you will see the SAML messages that are sent by the IDP.
### Obtaining the Service Provider Meta Data File
By default, the portal will automatically generate a Service Provider (SP) Meta Data File. You may need to provide this file to your Identity Provider (IP).
You can access the Service Provider Meta Data File via a URL such as:
[http://localhost:8080/cbioportal/saml/metadata](http://localhost:8080/cbioportal/saml/metadata)
# Authenticating and Authorizing Users via Keycloak
## Introduction
The cBioPortal includes support for Keycloak authentication. Keycloak can function as an Identity Provider (IDP) for cBioPortal.
This document explains why you might find Keycloak authentication useful for storing your user login information outside
the cBioPortal database. It also shows you how to configure Keycloak to communicate with your instance of cBioPortal using
SAML (Security Assertion Markup Language).
Please note that configuring your local instance to use Keycloak authentication requires a Keycloak server to be set up. For details on how to set up a Keycloak server, please read online document at <https://keycloak.gitbooks.io/documentation/server_installation/index.html>.
This document focuses mainly on the steps to configure Keycloak for **authenticating** and **authorizing** cBioPortal users.
To skip to the authorization section see: [authorization with Keycloak](#authorization-with-keycloak). Or continue reading to learn how to integrate Keycloak with cBioPortal.
### Why Keycloak?
Keycloak is an [open source identity and access management solution](https://keycloak.gitbooks.io/documentation/server_admin/topics/overview.html). It has a built-in RDBM system to store login information. It can help build a security layer on top of the cBioPortal web application.
Keycloak boils down to three simple terms:
* **realm**: A realm secures and manages security metadata for a set of users, application, and registered auth clients.
* **client**: Clients are entities that can request authentication of a user within a realm.
* **role**: Roles identify a type or category of user. Keycloak often assigns access and permissions to specific roles rather than individual users for a fine-grained access control.
Keycloak offers three types of roles:
* Realm-level roles are in global namespace shared by all clients.
* Client roles have basically a namespace dedicated to a client.
* A composite role is a role that has one or more additional roles associated with it.
### How does Keycloak SAML Authentication work?
Keycloak supports both OpenID-Connect and SAML authentication. When you use SAML authentication, the Keycloak server exchanges XML documents with a web application. XML signatures and encryption are then used to verify requests from the application.
## Configure Keycloak to authenticate your cbioportal instance
1. Log in to your Keycloak Identity Provider, e.g. <http://localhost:8080/auth>, as an admin user.
2. Hover over the top-left–corner drop down menu (titled ‘**Master**’) to create a new realm.
![](images/previews/add-realm.png)
Please note if you are logged in the master realm, this drop-down menu lists all the realms created. The last entry of this drop-down menu is always **Add Realm**. Click this to add a realm. Then type '_demo_' in the name field and click the **Create** button.
3. To create a SAML client, go to the **Clients** item in the left menu. On this page, click the **Create** button on the right. This will bring you to the **Add Client** page.
* Enter a **Client ID** for the client, e.g. '_cbioportal_', this will be the expected `issuer` value in SAML requests sent by the application.
* Select _saml_ in the **Client Protocol** drop down box.
* Enter `http://localhost:8081/cbioportal/saml` in the **Client SAML Endpoint** textbox, this is the URL that the Keycloak server will send SAML requests and responses to. Then click the **Save** button; this will take you to the client page below.
![](images/previews/edit-client.png)
4. Choose _email_ as your **Name ID Format**.
5. Next, enter a pattern for **Valid Redirect URIs** that Keycloak can use upon a successful authentication, e.g. `http://localhost:8081/cbioportal/*`. :information_source: notice that you can add multiple URLs in this field. You could use this in some cases to support
the URLs with and without port (e.g. if tomcat is running on port `80` and you want to allow both `http://localhost:80/cbioportal/*` and `http://localhost/cbioportal/*` as redirect URLs).
6. Set **Force POST Binding** and **Front Channel Logout** to _OFF_ and **Force Name ID Format** to _ON_.
7. Expand the subsection **Fine Grain SAML Endpoint Configuration** and set **Logout Service POST Binding URL** to `http://localhost:8081/cbioportal/saml/logout`.
8. Leave everything else as it is and click **Save**.
### Map SAML Assertion Attributes
To specify attributes included in the SAML assertion, simply click on the **Mappers** tab, and add mappers using the **Add Builtin** and **Create** buttons.
Make sure you add at least:
- the built-in User Property mapper named _X500 email_ and
- a _Role list_-type attribute using the word _roles_ as its **Role attribute name**.
![](images/previews/add-mappers.png)
Edit the email attribute to use the word _email_ as the **SAML Attribute Name**.
![](images/previews/edit-email-attribute.png)
Finally, head to the **Scope** tab for the client and switch off
**Full Scope Allowed**, to ensure that only those roles relevant to a
particular cBioPortal instance are listed in assertions sent to the
instance, and not any other roles tracked in Keycloak.
### Export configuration for cBioPortal
1. Next, navigate to the **Installation** tab for the same client.
2. Select _SAML Metadata IDPSSODescriptor_ as the Format Option and click the **Download** button.
4. Move the downloaded XML file to `portal/src/main/resources/`
![](images/previews/download-IDPSSODescriptor-file.png)
## Create a signing key for cBioPortal
Use the Java '`keytool`' command to generate keystore, as described
[here](Authenticating-Users-via-SAML.md#creating-a-keystore)
on the page about SAML in cBioPortal:
```
keytool -genkey -alias secure-key -keyalg RSA -keystore samlKeystore.jks
```
Install the generated JKS file to `portal/src/main/resources/`
In order to let Keycloak know that it can trust the holder of this
key, you'll need to import the key's certificate into Keycloak. In the
Keycloak admin screen about the `cbioportal` client, head to the
**SAML Keys** tab and click the **Import** button. Select the _JKS_
archive format, specify the key alias _secure-key_ and type the store
password _apollo1_ (not the private key password, as Keycloak only
needs to know the certificate), and select the file you just
installed. Keycloak may not give an indication of successful
completion, but when navigating to the **SAML Keys** tab again you
should now see the certificate and no private key.
## Modifying portal.properties
1. Within the portal.properties file , make sure that this line is present:
```
app.name=cbioportal
```
2. Then, modify the properties under the comment `# authentication`. In particular, see the options listed in the example below:
```properties
# authentication
authorization=true
authenticate=saml
filter_groups_by_appname=false
saml.sp.metadata.entityid=cbioportal
saml.idp.metadata.location=classpath:/client-tailored-saml-idp-metadata.xml
saml.idp.metadata.entityid=http://localhost:8080/auth/realms/demo
saml.keystore.location=classpath:/samlKeystore.jks
saml.keystore.password=apollo1
saml.keystore.private-key.key=secure-key
saml.keystore.private-key.password=apollo2
saml.keystore.default-key=secure-key
saml.idp.comm.binding.settings=defaultBinding
saml.idp.comm.binding.type=
saml.idp.metadata.attribute.email=email
saml.idp.metadata.attribute.role=roles
saml.custom.userservice.class=org.cbioportal.security.spring.authentication.keycloak.SAMLUserDetailsServiceImpl
# global logout (as opposed to local logout):
saml.logout.local=false
saml.logout.url=/
```
## Obtain user identities
### Optional: create users in Keycloak
To create a user, click on **Users** in the left menu bar. This menu
option brings you to the user list page. On the right side of the
empty user list, you should see an **Add User** button. Click that to
start creating your new user.
![](images/previews/add-user.png)
### Optional: integrate company-wide authentication services
Keycloak can read credentials from existing user databases, for
instance over LDAP. This is referred to as _user federation_. Keycloak
can also allow authentication by an external login form altogether
using a protocol such as SAML, it calls this _identity brokering_. In
either case, Keycloak acts as a proxy between your user directory and
cBioPortal, deciding which authorities to grant when telling