{"_id":"59e6190f2debd70010025b93","project":"55d535ca988e130d000b3f5c","version":{"_id":"55d535cb988e130d000b3f5f","__v":13,"project":"55d535ca988e130d000b3f5c","hasDoc":true,"hasReference":false,"createdAt":"2015-08-20T02:04:59.052Z","releaseDate":"2015-08-20T02:04:59.052Z","categories":["55d535cc988e130d000b3f60","55d6b238d2a8eb1900109eef","55d6b4f3250d7d0d004274cd","55d7967960fc730d00fc2852","55da9804e835f20d009fc5d0","55e75b1de06f4b190080dbfd","55e75b39e06f4b190080dbfe","55e75b7ae06f4b190080dbff","564f5a4e33082f0d001bb709","570fb64aa38d470e0060cbff","586d0dd89a854123001acd65","586d0e3b9a854123001acd66","5a613b28da07540012e8ca4a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"55e75b7ae06f4b190080dbff","__v":10,"project":"55d535ca988e130d000b3f5c","version":"55d535cb988e130d000b3f5f","pages":["5637e17197666c0d008656a5","569591a4fcb1032d0089e037","569622eafe18811700c9c19b","5696c9588560a60d00e2c1e0","569709ca0b09a41900b2442b","5697129ac8ded91700307b77","5697190a59a6692d003fad6a","5697192969393517000c8280","569f11908f6d4b0d00f13bb2","56a0030b5b981c2b00383df0"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-02T20:26:34.258Z","from_sync":false,"order":4,"slug":"frame-platform","title":"Frame Platform"},"user":"56461e119f3f550d00fa3da2","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-10-17T14:51:59.807Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":21,"body":"## Introduction\n\nFrame supports Single Sign-On (SSO) with Google authentication through both OAUTH2 and SAML2 integration options. The OAUTH2 option is the easiest to setup and can be done in under a minute, once your account has been granted the option. The SAML2 option is also relatively quick and easy, but does require more steps. We'll start with the first option:\n\n## OAUTH2 SSO Integration\n\nThis integration requires that you have a Frame for Business or Frame for Education account at the Pro tier or above. Also, any tier of Frame Platform supports this feature. However, since the option is not exposed by default, you'll need to send a request to support:::at:::fra.me to enable it for your account. Once enabled, click on the \"Authorize Google Users\" option from system menu on your Launchpad when logged in as an Admin:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d5db213-Screen_Shot_2018-04-05_at_4.06.06_PM.png\",\n        \"Screen Shot 2018-04-05 at 4.06.06 PM.png\",\n        219,\n        383,\n        \"#15304a\"\n      ]\n    }\n  ]\n}\n[/block]\nYou'll then see the following page, where you can specify either all users on one or more Google domains or specify individual users that you wish to grant access to:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d5c5d28-Screen_Shot_2018-04-05_at_4.10.35_PM.png\",\n        \"Screen Shot 2018-04-05 at 4.10.35 PM.png\",\n        623,\n        327,\n        \"#3f5062\"\n      ]\n    }\n  ]\n}\n[/block]\nYou can then instruct your users to navigate to your account's sign in page (yourteamurl.fra.me), select the \"Sign in with Google\" option and use their Google user name and password to sign in. They will be prompted to allow Frame access to their Google Drive the first time they sign in. Then, once they connect to their Frame account, it will automatically connect to their Google Drive (no further clicks or authentication steps are required). \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/898f18b-Screen_Shot_2018-04-05_at_4.15.36_PM.png\",\n        \"Screen Shot 2018-04-05 at 4.15.36 PM.png\",\n        386,\n        467,\n        \"#e0e1e4\"\n      ]\n    }\n  ]\n}\n[/block]\nIf you wish to show \"Sign-in with Google\" as the primary option when users navigate to your sign in page, you can set this in the [Customize](https://docs.fra.me/docs/launchpad-customization) menu:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2b5b94a-Screen_Shot_2018-04-05_at_4.19.24_PM.png\",\n        \"Screen Shot 2018-04-05 at 4.19.24 PM.png\",\n        290,\n        70,\n        \"#394d60\"\n      ]\n    }\n  ]\n}\n[/block]\nWith this option enabled, users will see the following when going to their sign-in page:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/93c09a0-Screen_Shot_2018-04-05_at_4.25.30_PM.png\",\n        \"Screen Shot 2018-04-05 at 4.25.30 PM.png\",\n        478,\n        498,\n        \"#7f8993\"\n      ]\n    }\n  ]\n}\n[/block]\nThat's it. You're now set up to use Sign in with Google on your account via our OAUTH2 integration option. If you prefer to set up your integration using SAML2, refer to the following section:\n\n## SAML2 SSO INTEGRATION\n\nNote that you will need to have a Google G Suite Account before we start. Also, make sure that you have a Platform Ultimate, sometimes called a \"Super Admin,\" account with Custom Authentication enabled. When this is enabled, you should see the \"Custom Authentications\" section in the Account menu for your Platform Ultimate account. If it is not enabled or if you aren't sure, contact your Frame Account Manager and ask about Custom Authentication.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b3672ee-1.png\",\n        \"1.png\",\n        635,\n        454,\n        \"#dbe1e1\"\n      ]\n    }\n  ]\n}\n[/block]\nYou will find the Custom Authentications option under the Account Menu for your Platform Ultimate account\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7cb8bf8-2.png\",\n        \"2.png\",\n        613,\n        216,\n        \"#649b7d\"\n      ]\n    }\n  ]\n}\n[/block]\nThe section you want is near the bottom of the page. Click \"Add New\"\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2a7a4ad-3.png\",\n        \"3.png\",\n        507,\n        651,\n        \"#e8eced\"\n      ]\n    }\n  ]\n}\n[/block]\nCreate a unique Custom Authentication name. The name should be something no one else will use and and it should be a valid hostname. This means it should be lower case, and have only letters, numbers, and the dash symbol, no spaces or punctuation are allowed. Select the account or accounts where users from this directory should be able to login.\n\nThe Entity ID will default to https://img.mainframe2.com if left blank, but can be set to any value required by your identity provider. Leave this blank if you are unsure.\n\nCheck \"Signed SAML2 Assertion\"\n\nMake sure \"Signed SAML2 Response\" is unchecked. - If you want to use signed responses, Frame supports this feature, but you will have to enable encrypted responses to enable this feature in Ping.\n\nClick \"Add\"\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a7e6e7e-4.png\",\n        \"4.png\",\n        1663,\n        741,\n        \"#395b77\"\n      ]\n    }\n  ]\n}\n[/block]\nWe will also want the Team URL from the account you want Users to access. You can find the Team URL by impersonating the account and looking in the location bar of your browser. In this example the Team URL is https://bill-2017-05-10-1.fra.me\n\n\n## Create A New Saml App In G Suite\n\nLogin to your G Suite Admin Panel\n\n### Step 1: Select Apps\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/000c358-1.png\",\n        \"1.png\",\n        1632,\n        396,\n        \"#d0d3d2\"\n      ]\n    }\n  ]\n}\n[/block]\n### Step 2: Select SAML apps\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0cb27f1-2.png\",\n        \"2.png\",\n        992,\n        684,\n        \"#e6e6e6\"\n      ]\n    }\n  ]\n}\n[/block]\n### Step 3: Create A New SAML App\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e31351d-3.png\",\n        \"3.png\",\n        1756,\n        940,\n        \"#4473d5\"\n      ]\n    }\n  ]\n}\n[/block]\nSelect the plus symbol to create a new SAML App.\n\n### Step 4: Create a Custom App\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f740a2d-4.png\",\n        \"4.png\",\n        1092,\n        714,\n        \"#d5d5d6\"\n      ]\n    }\n  ]\n}\n[/block]\nSelect \"SETUP MY OWN CUSTOM APP\"\n\n### Step 5: Download Metadata File\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/207d327-5.png\",\n        \"5.png\",\n        1021,\n        730,\n        \"#dbdbdb\"\n      ]\n    }\n  ]\n}\n[/block]\nScroll down and download the IDP Metadata file. You will be providing this to Frame Support later.\n\n### Step 6: Basic Details\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8434e5c-6.png\",\n        \"6.png\",\n        1005,\n        717,\n        \"#dadada\"\n      ]\n    }\n  ]\n}\n[/block]\nAdd a name, description and logo.\nHere's a Frame Logo if you need one: \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/67b78ab-7.png\",\n        \"7.png\",\n        215,\n        215,\n        \"#d01313\"\n      ]\n    }\n  ]\n}\n[/block]\n### Step 7: SAML Details\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7304022-8.png\",\n        \"8.png\",\n        998,\n        741,\n        \"#cecece\"\n      ]\n    }\n  ]\n}\n[/block]\nAssuming your custom authentication will be named: mycompany-gsuite\nAnd the account you want to provide access to has the team url: mycompany\nACS URL\nhttps://img.mainframe2.com/saml2/done/mycompany-gsuite/\nStart URL enter https://img.mainframe2.com/login/?account_type=mycompany-gsuite&return_url=https://mycompany.fra.me/custom_auth_return\nOtherwise set the fields as shown in the screenshot. Note that Signed Response is NOT checked. We only want the assertion to be signed.\n\n### Step 8: Attribute Mapping\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/63c03f1-9.png\",\n        \"9.png\",\n        1035,\n        739,\n        \"#dbdbda\"\n      ]\n    }\n  ]\n}\n[/block]\nThese should be spelled and capitalized exactly as given here.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b37388c-10.png\",\n        \"10.png\",\n        1110,\n        501,\n        \"#ebdbcd\"\n      ]\n    }\n  ]\n}\n[/block]\nYou should now see this message.\n\n### Final Step: Email Frame Support\n\n```\nHi Frame Support,\n\nI have created a new Google G Suite application for my Frame account.\n\nMy Frame Account is Called: Account NAME\nMy Frame Email Address is: me@example.com\nMy Team URL is: mycompany\nMy Custom Authentication Name is: mycompany-gsuite\n\nI have included my SAML Metadata File as requested (see attached).\n\nRegards,\n\nMe\n```\n\nEmail Frame Support (support@fra.me) and cc jason@fra.me and cgentry@fra.me. You can use this template for the email.\n\nProvide the same Team URL and Custom Authentication Name you provided in Step 7.\n\nWe will need a copy of your metadata file because G Suite does not support auto-discovery of metadata.\n\nFrame Support will create a Custom Authentication name and email you to let you know when the SSO integration is ready to test.\n\nThe Login URL will be: \n```\nhttps://img.mainframe2.com/login/?account_type=[Custom Auth Name]&return_url=https://[Team URL].fra.me/custom_auth_return\n```\ne.g.\n```\nhttps://img.mainframe2.com/login/?account_type=mycompany-gsuite&return_url=https://mycompany.fra.me/custom_auth_return\n```\nWhen you test, be sure to use an \"Incognito\" or \"Private Browsing\" window, to be sure your are really testing SSO and not just re-using an existing token in a cookie.","excerpt":"Use Sign in with Google to access your Frame account","slug":"integrating-with-g-suite-authentication","type":"basic","title":"Integrating with G Suite Authentication"}

Integrating with G Suite Authentication

Use Sign in with Google to access your Frame account

## Introduction Frame supports Single Sign-On (SSO) with Google authentication through both OAUTH2 and SAML2 integration options. The OAUTH2 option is the easiest to setup and can be done in under a minute, once your account has been granted the option. The SAML2 option is also relatively quick and easy, but does require more steps. We'll start with the first option: ## OAUTH2 SSO Integration This integration requires that you have a Frame for Business or Frame for Education account at the Pro tier or above. Also, any tier of Frame Platform supports this feature. However, since the option is not exposed by default, you'll need to send a request to support@fra.me to enable it for your account. Once enabled, click on the "Authorize Google Users" option from system menu on your Launchpad when logged in as an Admin: [block:image] { "images": [ { "image": [ "https://files.readme.io/d5db213-Screen_Shot_2018-04-05_at_4.06.06_PM.png", "Screen Shot 2018-04-05 at 4.06.06 PM.png", 219, 383, "#15304a" ] } ] } [/block] You'll then see the following page, where you can specify either all users on one or more Google domains or specify individual users that you wish to grant access to: [block:image] { "images": [ { "image": [ "https://files.readme.io/d5c5d28-Screen_Shot_2018-04-05_at_4.10.35_PM.png", "Screen Shot 2018-04-05 at 4.10.35 PM.png", 623, 327, "#3f5062" ] } ] } [/block] You can then instruct your users to navigate to your account's sign in page (yourteamurl.fra.me), select the "Sign in with Google" option and use their Google user name and password to sign in. They will be prompted to allow Frame access to their Google Drive the first time they sign in. Then, once they connect to their Frame account, it will automatically connect to their Google Drive (no further clicks or authentication steps are required). [block:image] { "images": [ { "image": [ "https://files.readme.io/898f18b-Screen_Shot_2018-04-05_at_4.15.36_PM.png", "Screen Shot 2018-04-05 at 4.15.36 PM.png", 386, 467, "#e0e1e4" ] } ] } [/block] If you wish to show "Sign-in with Google" as the primary option when users navigate to your sign in page, you can set this in the [Customize](https://docs.fra.me/docs/launchpad-customization) menu: [block:image] { "images": [ { "image": [ "https://files.readme.io/2b5b94a-Screen_Shot_2018-04-05_at_4.19.24_PM.png", "Screen Shot 2018-04-05 at 4.19.24 PM.png", 290, 70, "#394d60" ] } ] } [/block] With this option enabled, users will see the following when going to their sign-in page: [block:image] { "images": [ { "image": [ "https://files.readme.io/93c09a0-Screen_Shot_2018-04-05_at_4.25.30_PM.png", "Screen Shot 2018-04-05 at 4.25.30 PM.png", 478, 498, "#7f8993" ] } ] } [/block] That's it. You're now set up to use Sign in with Google on your account via our OAUTH2 integration option. If you prefer to set up your integration using SAML2, refer to the following section: ## SAML2 SSO INTEGRATION Note that you will need to have a Google G Suite Account before we start. Also, make sure that you have a Platform Ultimate, sometimes called a "Super Admin," account with Custom Authentication enabled. When this is enabled, you should see the "Custom Authentications" section in the Account menu for your Platform Ultimate account. If it is not enabled or if you aren't sure, contact your Frame Account Manager and ask about Custom Authentication. [block:image] { "images": [ { "image": [ "https://files.readme.io/b3672ee-1.png", "1.png", 635, 454, "#dbe1e1" ] } ] } [/block] You will find the Custom Authentications option under the Account Menu for your Platform Ultimate account [block:image] { "images": [ { "image": [ "https://files.readme.io/7cb8bf8-2.png", "2.png", 613, 216, "#649b7d" ] } ] } [/block] The section you want is near the bottom of the page. Click "Add New" [block:image] { "images": [ { "image": [ "https://files.readme.io/2a7a4ad-3.png", "3.png", 507, 651, "#e8eced" ] } ] } [/block] Create a unique Custom Authentication name. The name should be something no one else will use and and it should be a valid hostname. This means it should be lower case, and have only letters, numbers, and the dash symbol, no spaces or punctuation are allowed. Select the account or accounts where users from this directory should be able to login. The Entity ID will default to https://img.mainframe2.com if left blank, but can be set to any value required by your identity provider. Leave this blank if you are unsure. Check "Signed SAML2 Assertion" Make sure "Signed SAML2 Response" is unchecked. - If you want to use signed responses, Frame supports this feature, but you will have to enable encrypted responses to enable this feature in Ping. Click "Add" [block:image] { "images": [ { "image": [ "https://files.readme.io/a7e6e7e-4.png", "4.png", 1663, 741, "#395b77" ] } ] } [/block] We will also want the Team URL from the account you want Users to access. You can find the Team URL by impersonating the account and looking in the location bar of your browser. In this example the Team URL is https://bill-2017-05-10-1.fra.me ## Create A New Saml App In G Suite Login to your G Suite Admin Panel ### Step 1: Select Apps [block:image] { "images": [ { "image": [ "https://files.readme.io/000c358-1.png", "1.png", 1632, 396, "#d0d3d2" ] } ] } [/block] ### Step 2: Select SAML apps [block:image] { "images": [ { "image": [ "https://files.readme.io/0cb27f1-2.png", "2.png", 992, 684, "#e6e6e6" ] } ] } [/block] ### Step 3: Create A New SAML App [block:image] { "images": [ { "image": [ "https://files.readme.io/e31351d-3.png", "3.png", 1756, 940, "#4473d5" ] } ] } [/block] Select the plus symbol to create a new SAML App. ### Step 4: Create a Custom App [block:image] { "images": [ { "image": [ "https://files.readme.io/f740a2d-4.png", "4.png", 1092, 714, "#d5d5d6" ] } ] } [/block] Select "SETUP MY OWN CUSTOM APP" ### Step 5: Download Metadata File [block:image] { "images": [ { "image": [ "https://files.readme.io/207d327-5.png", "5.png", 1021, 730, "#dbdbdb" ] } ] } [/block] Scroll down and download the IDP Metadata file. You will be providing this to Frame Support later. ### Step 6: Basic Details [block:image] { "images": [ { "image": [ "https://files.readme.io/8434e5c-6.png", "6.png", 1005, 717, "#dadada" ] } ] } [/block] Add a name, description and logo. Here's a Frame Logo if you need one: [block:image] { "images": [ { "image": [ "https://files.readme.io/67b78ab-7.png", "7.png", 215, 215, "#d01313" ] } ] } [/block] ### Step 7: SAML Details [block:image] { "images": [ { "image": [ "https://files.readme.io/7304022-8.png", "8.png", 998, 741, "#cecece" ] } ] } [/block] Assuming your custom authentication will be named: mycompany-gsuite And the account you want to provide access to has the team url: mycompany ACS URL https://img.mainframe2.com/saml2/done/mycompany-gsuite/ Start URL enter https://img.mainframe2.com/login/?account_type=mycompany-gsuite&return_url=https://mycompany.fra.me/custom_auth_return Otherwise set the fields as shown in the screenshot. Note that Signed Response is NOT checked. We only want the assertion to be signed. ### Step 8: Attribute Mapping [block:image] { "images": [ { "image": [ "https://files.readme.io/63c03f1-9.png", "9.png", 1035, 739, "#dbdbda" ] } ] } [/block] These should be spelled and capitalized exactly as given here. [block:image] { "images": [ { "image": [ "https://files.readme.io/b37388c-10.png", "10.png", 1110, 501, "#ebdbcd" ] } ] } [/block] You should now see this message. ### Final Step: Email Frame Support ``` Hi Frame Support, I have created a new Google G Suite application for my Frame account. My Frame Account is Called: Account NAME My Frame Email Address is: me@example.com My Team URL is: mycompany My Custom Authentication Name is: mycompany-gsuite I have included my SAML Metadata File as requested (see attached). Regards, Me ``` Email Frame Support (support@fra.me) and cc jason@fra.me and cgentry@fra.me. You can use this template for the email. Provide the same Team URL and Custom Authentication Name you provided in Step 7. We will need a copy of your metadata file because G Suite does not support auto-discovery of metadata. Frame Support will create a Custom Authentication name and email you to let you know when the SSO integration is ready to test. The Login URL will be: ``` https://img.mainframe2.com/login/?account_type=[Custom Auth Name]&return_url=https://[Team URL].fra.me/custom_auth_return ``` e.g. ``` https://img.mainframe2.com/login/?account_type=mycompany-gsuite&return_url=https://mycompany.fra.me/custom_auth_return ``` When you test, be sure to use an "Incognito" or "Private Browsing" window, to be sure your are really testing SSO and not just re-using an existing token in a cookie.