{"_id":"5a3412f50974d00026737eb6","project":"55d535ca988e130d000b3f5c","version":{"_id":"55d535cb988e130d000b3f5f","__v":12,"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"],"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-12-15T18:22:45.293Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":24,"body":"## Introduction\nIntegrating Okta Single Single-On (SSO) is a quick and easy process.\n\nIf you would like to integrate using the FrameAPP API, much of this is the same, but you will want to talk to your Frame Account Manager to discuss integration options.\n\nThere are four things we are going to cut and paste from one system to the other.\n\n+ The Frame **Custom Authentication Name**. This is a name you pick when you create the custom authentication (see below).\n+ The Frame **Team URL** for the Frame account you want users to access.\n+ The Okta  **Federation Metadata Document URL**. This is a URL where Okta keeps the SAML Metadata for your account.\n\nFollowing the steps below, you can find these values and copy them from Okta to Frame and from Frame to Okta. This process should take less than fifteen minutes.\n\nFirst, 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\n## Step 1: Create The Custom Authentication\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e00a8eb-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[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5f71b76-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\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/bc92b4d-custom_authentication.png\",\n        \"custom_authentication.png\",\n        507,\n        651,\n        \"#e9edee\"\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.\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[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cd0a2b1-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\nThat's all we need from Frame. Now let's gather what we need from Okta\n\n## Step 2: Setup Okta\n\nLogin to your Okta account as an Admin and open the Dashboard.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2be1846-dashboard.png\",\n        \"dashboard.png\",\n        1633,\n        383,\n        \"#2c6abc\"\n      ]\n    }\n  ]\n}\n[/block]\nSelect \"Add Applications\"\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/509d4d8-create_application.png\",\n        \"create_application.png\",\n        794,\n        597,\n        \"#2b68b9\"\n      ]\n    }\n  ]\n}\n[/block]\nSelect \"Create New App\"\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d33dcb5-saml2.png\",\n        \"saml2.png\",\n        1203,\n        731,\n        \"#f8f8f8\"\n      ]\n    }\n  ]\n}\n[/block]\nChoose \"SAML 2.0\"\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/9c954d0-name_application.png\",\n        \"name_application.png\",\n        1405,\n        876,\n        \"#2c6fc0\"\n      ]\n    }\n  ]\n}\n[/block]\nProvide a name and icon.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/482da4f-frame_logo.png\",\n        \"frame_logo.png\",\n        300,\n        110,\n        \"#c8301f\"\n      ]\n    }\n  ]\n}\n[/block]\nYou can use this icon, or one of your own.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b1a02a0-SAML_settings.png\",\n        \"SAML_settings.png\",\n        1250,\n        793,\n        \"#f7f8f9\"\n      ]\n    }\n  ]\n}\n[/block]\nFill-in the Single Sign-on URL.\n\nThis will be in the form https://img.mainframe2.com/saml2/done/[CUSTOM_AUTHENTICATION_NAME]/\n\nIn this example that would be:\nhttps://img.mainframe2.com/saml2/done/mycompany-okta/\n\nFor the Audience URI (Entity ID),  \"img.mainframe2.com\"  is the default, but any combination of numbers, letters, dashes '-' and periods '.' will work, but be sure to use the same value here and in the Entity ID  in the Custom Authentication.\n\nSelect \"Show Advanced Settings\"\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ec52395-more_SAML_settings.png\",\n        \"more_SAML_settings.png\",\n        955,\n        401,\n        \"#fbfbfa\"\n      ]\n    }\n  ]\n}\n[/block]\nChange \"Response\" to \"Unsigned\". Leave default values for the rest.\n\nScroll down.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/02586b7-SAML_attributes.png\",\n        \"SAML_attributes.png\",\n        1080,\n        516,\n        \"#fafafa\"\n      ]\n    }\n  ]\n}\n[/block]\nAdd three \"Attribute Statements.\" They must be exactly as shown here, including capitalization.\n\nSelect \"Next\"\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5601885-SAML_metadata.png\",\n        \"SAML_metadata.png\",\n        1107,\n        814,\n        \"#f8f8f7\"\n      ]\n    }\n  ]\n}\n[/block]\nHover over the Identity Provider Metadata link. You should see something similar, but not identical to, the example. Copy that link and save it for the next step.\n\nAuthorize whatever groups or users you want to allow to use the Frame App in whichever way you normally manage app permission in Okta.  See the Okta documentation if you have questions.\n\nThat finishes the setup on the Okta side. \n\n## Step 3: Paste Federation Metadata Document URL into the Frame Custom Authentication\n\nGo back to Frame. Go to your Platform Ultimate Account menu.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3873d9f-custome_authentication_list.png\",\n        \"custome_authentication_list.png\",\n        1135,\n        279,\n        \"#e9f1f1\"\n      ]\n    }\n  ]\n}\n[/block]\n  Edit the Custom Authentication you created earlier.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2ef339b-paste_metadata.png\",\n        \"paste_metadata.png\",\n        501,\n        647,\n        \"#e8eced\"\n      ]\n    }\n  ]\n}\n[/block]\nPaste the Federation Metadata Document URL into the Customer Metatdata URL field.\n\nSet the \"Entity ID\" to:\n\nimg.mainframe2.com\n\nNote that we selected \"Signed SAML2 Assertion\" earlier.\n\nClick \"Save Changes\"\n\nIf your organization's network policies do not allow access to the Federation Metadata Document URL, we can also copy your Metadata Document manually. Please contact support:::at:::fra.me and provide the name of your Custom Authentication for help.\n\n## Using the New Custom Authentication\n\nUsers will now be able to authenticate using the Sign-on URL \n\n**https://img.mainframe2.com/login/?account_type=[CUSTOM_AUTHENTICATION_NAME]&return_url=ttps://[TEAM_URL].fra.me/custom_auth_return**\n\nFor our example this would be:\n\n**https://img.mainframe2.com/login/?account_type=mycompany-okta&return_url=https://bill-2017-05-10-1.fra.me/custom_auth_return**","excerpt":"","slug":"integrating-with-okta","type":"basic","title":"Integrating with Okta"}

Integrating with Okta


## Introduction Integrating Okta Single Single-On (SSO) is a quick and easy process. If you would like to integrate using the FrameAPP API, much of this is the same, but you will want to talk to your Frame Account Manager to discuss integration options. There are four things we are going to cut and paste from one system to the other. + The Frame **Custom Authentication Name**. This is a name you pick when you create the custom authentication (see below). + The Frame **Team URL** for the Frame account you want users to access. + The Okta **Federation Metadata Document URL**. This is a URL where Okta keeps the SAML Metadata for your account. Following the steps below, you can find these values and copy them from Okta to Frame and from Frame to Okta. This process should take less than fifteen minutes. First, 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. ## Step 1: Create The Custom Authentication [block:image] { "images": [ { "image": [ "https://files.readme.io/e00a8eb-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/5f71b76-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/bc92b4d-custom_authentication.png", "custom_authentication.png", 507, 651, "#e9edee" ] } ] } [/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. 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/cd0a2b1-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 That's all we need from Frame. Now let's gather what we need from Okta ## Step 2: Setup Okta Login to your Okta account as an Admin and open the Dashboard. [block:image] { "images": [ { "image": [ "https://files.readme.io/2be1846-dashboard.png", "dashboard.png", 1633, 383, "#2c6abc" ] } ] } [/block] Select "Add Applications" [block:image] { "images": [ { "image": [ "https://files.readme.io/509d4d8-create_application.png", "create_application.png", 794, 597, "#2b68b9" ] } ] } [/block] Select "Create New App" [block:image] { "images": [ { "image": [ "https://files.readme.io/d33dcb5-saml2.png", "saml2.png", 1203, 731, "#f8f8f8" ] } ] } [/block] Choose "SAML 2.0" [block:image] { "images": [ { "image": [ "https://files.readme.io/9c954d0-name_application.png", "name_application.png", 1405, 876, "#2c6fc0" ] } ] } [/block] Provide a name and icon. [block:image] { "images": [ { "image": [ "https://files.readme.io/482da4f-frame_logo.png", "frame_logo.png", 300, 110, "#c8301f" ] } ] } [/block] You can use this icon, or one of your own. [block:image] { "images": [ { "image": [ "https://files.readme.io/b1a02a0-SAML_settings.png", "SAML_settings.png", 1250, 793, "#f7f8f9" ] } ] } [/block] Fill-in the Single Sign-on URL. This will be in the form https://img.mainframe2.com/saml2/done/[CUSTOM_AUTHENTICATION_NAME]/ In this example that would be: https://img.mainframe2.com/saml2/done/mycompany-okta/ For the Audience URI (Entity ID), "img.mainframe2.com" is the default, but any combination of numbers, letters, dashes '-' and periods '.' will work, but be sure to use the same value here and in the Entity ID in the Custom Authentication. Select "Show Advanced Settings" [block:image] { "images": [ { "image": [ "https://files.readme.io/ec52395-more_SAML_settings.png", "more_SAML_settings.png", 955, 401, "#fbfbfa" ] } ] } [/block] Change "Response" to "Unsigned". Leave default values for the rest. Scroll down. [block:image] { "images": [ { "image": [ "https://files.readme.io/02586b7-SAML_attributes.png", "SAML_attributes.png", 1080, 516, "#fafafa" ] } ] } [/block] Add three "Attribute Statements." They must be exactly as shown here, including capitalization. Select "Next" [block:image] { "images": [ { "image": [ "https://files.readme.io/5601885-SAML_metadata.png", "SAML_metadata.png", 1107, 814, "#f8f8f7" ] } ] } [/block] Hover over the Identity Provider Metadata link. You should see something similar, but not identical to, the example. Copy that link and save it for the next step. Authorize whatever groups or users you want to allow to use the Frame App in whichever way you normally manage app permission in Okta. See the Okta documentation if you have questions. That finishes the setup on the Okta side. ## Step 3: Paste Federation Metadata Document URL into the Frame Custom Authentication Go back to Frame. Go to your Platform Ultimate Account menu. [block:image] { "images": [ { "image": [ "https://files.readme.io/3873d9f-custome_authentication_list.png", "custome_authentication_list.png", 1135, 279, "#e9f1f1" ] } ] } [/block] Edit the Custom Authentication you created earlier. [block:image] { "images": [ { "image": [ "https://files.readme.io/2ef339b-paste_metadata.png", "paste_metadata.png", 501, 647, "#e8eced" ] } ] } [/block] Paste the Federation Metadata Document URL into the Customer Metatdata URL field. Set the "Entity ID" to: img.mainframe2.com Note that we selected "Signed SAML2 Assertion" earlier. Click "Save Changes" If your organization's network policies do not allow access to the Federation Metadata Document URL, we can also copy your Metadata Document manually. Please contact support@fra.me and provide the name of your Custom Authentication for help. ## Using the New Custom Authentication Users will now be able to authenticate using the Sign-on URL **https://img.mainframe2.com/login/?account_type=[CUSTOM_AUTHENTICATION_NAME]&return_url=ttps://[TEAM_URL].fra.me/custom_auth_return** For our example this would be: **https://img.mainframe2.com/login/?account_type=mycompany-okta&return_url=https://bill-2017-05-10-1.fra.me/custom_auth_return**