What is Koxa Partners Portal?

Koxa Partners Portal (KPP) provides bank partners access to a number of Koxa’s administrative tools and resources.

Support Ticketing to submit and track issues escalated to Koxa for live customers, and to submit and track partner requests including documentation, training, and product enhancements
Customer Enrollment submit and track customer enrollment requests
Sales Enablement assets including videos, self-service demos, FAQs, and templates
Partner Guides on using Koxa's partner-facing tools
ERP Plug-In Product Guides for customers describing plug-in configuration, activation and usage; these are also useful for partner onboarding and support teams
Release Notes describing ERP plug-in enhancements and fixes; Koxa’s release notes enable partners to subscribe for product updates by email
Platform Availability uptime dashboard, upcoming maintenance windows, downtime reports; Koxa’s dashboards enable partners to subscribe for availability updates by email

Scope of SSO Access

SSO provides bank partner-managed access to KPP, hosted by Zendesk, via your identity provider (e.g. Ping, Okta, Microsoft AD), to Okta, Koxa’s identity provider, then onto KPP.

Koxa partner SSO utilizes SAML 2.0 assertion from the partner’s IdP to Okta, with redirection to KPP. This ensures the partner is responsible for defining the population of users who can access KPP and the authentication factors (i.e. user password, MFA, allow-listing access to sign in).

The partner manages which individuals, roles, or groups can access KKP via SSO.
- Koxa does not allow direct authentication to KPP; SSO is the only entry point for partners.
Koxa manages which individuals are granted elevated access to sensitive partner resources, see User Provisioning and Access below.
- Elevated access can be requested by support
Koxa Partners Portal does not support SCIM, nor custom role/entitlement mapping.

Navigation to Koxa Partners Portal

Koxa partners can to navigate to KPP in several ways:

Direct browser navigation to partners.koxa.io
IdP-initiated SSO redirection to partners.koxa.io
Following links within an email notification for a support or enrollment request

In all cases, user is routed to authenticate via SSO, then redirected to their destination.

Partner Set-Up Guide

1. SSO Configuration in Your IdP

Configure a custom SAML application in your IdP. Koxa's claim requirements are simple and we do not support customized claim values.

Service Name	Unique identifier for this SSO connection, typically follows your internal naming convention.
First Name	Part of user’s display name.
Last Name	Part of user’s display name.
Email	This is Koxa Partner Portal’s primary identifier for the user.

SAML Sample Snippet with Koxa's Required Claims

<md:AttributeConsumingService index="0">
    <md:ServiceName xml:lang="en">Koxa-Sample-IdP</md:ServiceName>
    <md:RequestedAttribute FriendlyName="First Name" Name="firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true" />
    <md:RequestedAttribute FriendlyName="Last Name" Name="lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true" />
    <md:RequestedAttribute FriendlyName="Email" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true" />
</md:AttributeConsumingService>

2. Send Koxa Implementations Your Metadata, Sample, and Certificate

When you have completed your initial IDP configuration, please email your metadata, sample SAML assertion, and certificate to bankpartner@koxa.io.

Your Metadata

Service Name	Please note the unique name for SSO connection to Koxa Partner’s Portal
First Name	Please note the unique claim name, such as `firstName` or `givenName`
Last Name	Please note the unique claim name, such as `lastName` or `surname`
Email	Please note the unique claim name, such as `email` or `emailAddress`

Sample SAML Assertion

In addition to your metadata, you must provide an actual SAML assertion from your IdP. Many IdPs (Microsoft Entra especially) export a standardized metadata file that does not reflect the attributes/claims as they actually exist in your environment.

If you provide only metadata without a sample assertion, Koxa cannot begin configuration. This tutorial provides a guide to capturing a sample.

If you need an Entity ID/ACS to build your initial IdP connection before you have these details from Koxa, use Koxa-Sample-IdP (or any placeholder value); Koxa will provide your real values once we've received and reviewed your sample assertion.

X.509 Certificate

.pem format is preferred

3. Koxa Configures Our IdP

Once we have your details, Koxa configures our IdP to accept your SAML assertion and replies with:

A unique Entity Descriptor representing your SSO provider in Koxa's IdP
Koxa's public certificate (.pem)
Instructions to validate SSO access

4. Validate and Go Live

Follow the provided instructions to validate SSO access. Once validated, you may provision your users for Koxa Partners Portal access. If your users can't access the portal, reply to this thread for assistance.

User Provisioning and Access

Your users will be provisioned using the “JIT” — just in time — approach: each user will be created in Koxa’s IdP the first time they sign in via SSO. There is no need to pre-enroll users for access.

All users will be assigned Koxa’s baseline partner role. In addition, users are assigned to an organization that segments access to Koxa Partners Portal resources per partner. Your team may request elevated access roles for particular users on your team through a support request:

The partner role enables users to access KPP content, submit support requests, and access/respond to their own requests (and those they are directly CC'd on).
The enrollment role enables users to submit enrollment requests; once submitted these requests are tracked the same way as support requests following the baseline partner accress described above.
The organization role enables users to access/respond to all support/enrollment requests for the entire partner organization.

Enrollment and Organization roles are assigned by Koxa, per user, through a support request. Koxa does not support attribute or group-based role mapping through the SAML assertion.

User Deprovisioning

Users are deprovisioned entirely within your IdP. When a user is offboarded, a record of their user will continue to exist in Koxa’s IdP, but they will have no means to authenticate or access Koxa Partners Portal resources. Koxa retains a permanent record that the user existed, we do not deprovision users.

Appendix

Sample Koxa Metadata

Reference only, this is a generic sample, not your Bank-specific configuration. Your actual values will be issued after Koxa completes Step 3 above.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor entityID="https://www.okta.com/saml2/service-provider/spwsuopkdfhyytk"
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIDmDCCAoCgAwIBAgIGAXVQ...[truncated]...RBlvr3M74edPpuTWR2Poz8z0gwJUSXnr6qwfgHATH</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
      <md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
      <md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes192-cbc"/>
      <md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
      <md:EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes128-gcm"/>
      <md:EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes256-gcm"/>
      <md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
    </md:KeyDescriptor>
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIDmDCCAoCgAwIBAgIGAXVQq9iEMA0GC...[truncated]...FonRx2/ZlX1sGT47HBBtsVKh2a94fe+SF</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://auth.koxa.dev/sso/saml2/0oaelueftp42LUqQ92e8" index="0" isDefault="true"/>
    <md:AttributeConsumingService index="0">
      <md:ServiceName xml:lang="en">Koxa-Sample-IdP</md:ServiceName>
      <md:RequestedAttribute FriendlyName="First Name" Name="firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
      <md:RequestedAttribute FriendlyName="Last Name" Name="lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
      <md:RequestedAttribute FriendlyName="Email" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
      <md:RequestedAttribute FriendlyName="Mobile Phone" Name="mobilePhone" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="false"/>
    </md:AttributeConsumingService>
  </md:SPSSODescriptor>
  <md:Organization>
    <md:OrganizationName xml:lang="en">koxa</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="en">Koxa</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="en">http://koxa.io</md:OrganizationURL>
  </md:Organization>
</md:EntityDescriptor>

FAQ

What is my Partner Portal URL?

All partners access through the same URL: https://partners.koxa.io

Who gets access to Koxa Partners Portal via SSO?

Employees of Koxa's partner banks via SSO. (Your customers, Bank Connect end users, do not access our partner portal and do not authenticate via your IdP.)

Do all users get the same level of access?

All users will be assigned Koxa’s baseline partner role. In addition, users are assigned to an organization that segments access to Koxa Partners Portal resources per partner. You can request elevated access for particular users on your team through a support request.

Does SSO support granular permissioning via SAML assertion?

Not at this time. If this becomes available in the future, Koxa Implementations will proactively connect with you.

Can I bookmark Koxa Partners Portal?

Yes, we encourage it. Your IT team may also want to add the URL as an intranet bookmark.

Koxa’s IdP assigns a bookmark app pointed to KPP to all users upon JIT provisioning. This can be toggled by each user to automatically direct them to https://partners.koxa.io whenever they sign in. This toggle enables IdP-initiated SSO.

Does Koxa support a non-production environment for testing?

Yes, with more setup work than a standard build. You'll need to provide both non-production and production metadata/certs upfront so Koxa can configure both. Once non-production testing is validated, we'll switch the connection to production for your final validation and go-live.

Note: There is only one Koxa Partners Portal, your non-production SSO will still resolve here.

What happens if SSO isn't working?

Please open a support request for troubleshooting.

Setting Up SSO for Koxa Partners Portal